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INTRODUCTION 



COMMODORE 128 



The Commodore 128 Personal Computer is a versatile, multimode computer. The 
Commodore 128 is the successor to the commercially successful Commodore 64 com- 
puter. The principal features of the Commodore 128 are: \ i 



128K bytes of RAM, optionally expandable to 256K or 640K 

80-column horizontal screen display 

Hardware and software compatibility with Commodore 64 

CP/M 3.0 operation 

Enhanced BASIC language 



C128 Mode 
C64 Mode 
CP/M Mode 



CI 28 MODE 



In C128 Mode, the Commodore 128 Personal Computer provides the capabilities and 
memory needed to run sophisticated applications, such as word processing, spreadsheets, 
and database programs. 

CI 28 Mode features include: 






Ij 



As this Guide shows, the Commodore 128 has many other new or expanded 
capabilities and features. Those listed above, however, are the most significant when \ ] 

assessing the Commodore 128's capabilities against those of the Commodore 64 and !j 

other microcomputers. 

The Commodore 128 is actually three computers in one, with the following three 
primary operating modes: 



u 



Two of these primary modes (CI 28 and CP/M) can operate using either a 40- or j l 

80-column screen display. Following is a summary of the major features of each of the 
three primary operating modes. 
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8502 processor running at 1.02 or 2.04 MHz 

New, enhanced CI 28 Kemal 

Built-in machine language monitor , / 

Commodore BASIC 7.0 language, with over 140 commands and functions } I 

Special new BASIC 7.0 commands that provide better, quicker and easier ways 

to create complex graphics, animation, sound and music programs 

40-c61umn text and bit map screen output using VIC II chip 

80-column text screen output using 8563 chip 
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NOTE: The 40- and 80-column screen displays can be used either singly 
or simultaneously with two monitors. 



Sound (three voices) using SID chip 

A 92-key keyboard that includes a full numeric keypad and ESCAPE, TAB, 

ALT, CAPS LOCK, HELP, LINE FEED, 40/80 DISPLAY, and NO SCROLL 

keys 

Access to the full capabilities of the new peripheral devices from Commodore 

(1571 fast disk drive, 1902 dual 40/80-column RGBI monitor, etc.) 

Access to all standard Commodore serial peripherals 

RAM expansion to 256 or 640K with optional RAM expansion modules 
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C64 MODE 



In C64 Mode, the Commodore 128 retains all the capabilities of the Commodore 64, 
thus allowing you to use the wide range of available Commodore 64 software. 
C64 Mode features include: 
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8502 processor running at 1 .02 MHz 

Standard C64 Kemal 

BASIC 2.0 language 

64K of RAM 

40-column output using VIC II chip 

Sound (three voices) using SID chip 

Standard Commodore 64 keyboard layout except for function keys 

All standard Commodore 64 keyboard functions 

Access to all Commodore 64 graphics, color and sound capabilities, used 

as on a Commodore 64 

Compatibility with standard Commodore 64 peripherals, including user port and 

serial devices, Datassette, joysticks, composite video monitors, and RF 

(TV) output devices 
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NOTE: The 1571 disk drive will function in C64 Mode, but only 
at standard 1541 speed. C64 compatibility requirements make it impossi- 
ble for the 1571 to operate in C64 Mode at fast speed. 



COMMODORE I2S 



CP/M MODE 



In CP/M Mode, an onboard Z80 microprocessor gives you access to the capabilities of 
Digital Research's CP/M Version 3.0, plus a number of new capabilities added by Commodore. 
CP/M Mode features include: 



HARDWARE COMPONENTS 

The Commodore 128 Personal Computer incorporates the following major hardware 
components: 

PROCESSORS 

8502: Main processor in C128, C64 Modes; I/O support for CP/M; 6502 software- 
compatible; runs at 1.02 or 2.04 MHz 
Z80: CP/M Mode only; runs at 2.04 MHz 

MEMORY 

ROM; 64K standard (C64 Kemal plus BASIC; C128 Kemal plus BASIC, character 

ROMs and CP/M BIOS); one 32K slot available for software 
RAM: 128K in two 64K banks; 16K display RAM for 8563 video chip; 2K x 4 Color RAM 

VIDEO 

8564: 40-column video (separate versions for NTSC and PAL TV standards) 
8563: 80-column video 
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■ Integral Z80 processor running at 2.04 MHz 

■ Disk-based CP/M 3.0 System 

■ 128K bytes of RAM (in 64K banks) 

■ 40-column screen output using VIC II chip 

■ 80-column screen output using 8563 chip 

■ Access to the full keyboard, including the numeric keypad and special keys ) / 

■ Access to the new fast serial disk drive (1571) and the standard serial peripherals [J 

■ Ability to redefine almost any key 

■ Ability to emulate several terminals (Lear-Siegler ADM31, ADM3 A) 

■ Support for various MFM disk formats (IBM, Kaypro, Epson, Osborne) 

■ RAM expansion to 256 or 640K RAM with optional RAM expansion modules '-' 

The incorporation of CP/M 3.0 (also called CP/M Plus) into the Commodore 128 \"\ 

makes thousands of popular commercial and public domain software programs available [j 

to the user. 
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SOUND 

658/: SID Chip 

INPUT/OUTPUT 

6526: Joystick ports/keyboard scan/cassette 
6526: User and serial ports 

MEMORY MANAGEMENT 

8921: PLA (C64 plus C128 mapping modes) 
8922: MMU (Custom gate array) 



For details on these and other hardware components see Chapter 16, Commodore 
n 128 Hardware Specifications. 



COMPATIBIUTY WITH 
COMMODORE 64 

The Commodore 128 system is designed as an upgrade to the Commodore 64. Accord- 
ingly, one of the major features of the Conimodore 128 design is hardware and software 
compatibility with the Commodore 64 when operating in C64 Mode. This means that in 
C64 Mode the Commodore 128 is capable of running Commodore 64 application 
software. Also, the Commodore 128 in C64 Mode supports Commodore 64 peripherals 
except the CP/M 2.2 cartridge. (NOTE: The Conimodore 128's built-in CP/M 3.0 
capability supersedes that provided by the external cartridge. This cartridge should not 
be used with the Commodore 128 in any mode.) 

The CI 28 Mode is designed as a compatible superset to the C64. Specifically, all 
Kemal functions provided by the Commodore 64 are provided in the C128 Kemal. 
These functions are also provided at the same locations in the jump table of the CI 28 
Kemal to provide compatibility with existing programs. Zero page and other system 
variables are maintained at the same addresses they occupy in C64 Mode. This simpli- 
fies interfacing for many programs. 

Providing Commodore 64 compatibility means that the new features of the Com- 
modore 128 cannot be accessed in C64 Mode. For example, compatibility and memory 
constraints preclude modifying the C64 Mode Kemal to support the 1571 fast serial disk 
drive. As noted previously, C64 Mode sees this drive as a standard serial disk drive. For 
the same reason, C64 Mode does not have an 80-column screen editor, and C64 Mode 
BASIC 2.0 cannot use the second 64K bank of memory. 



COMMODORE 128 



u 



SWITCHING FROM MODE TO MODE 



As mentioned before, in the C128 and CP/M Modes the Commodore 128 can provide 
both 40-column and 80-colunm screen displays. This means that the Commodore 128 
actually has five operating modes, as follows: 

■ CI 28 Mode with 80-column display 

■ CI 28 Mode with 40-column display 

■ C64 Mode (40-colunnn display only) 

■ CP/M Mode with 80-column display 

■ CP/M Mode with 40-column display 

Figure 1-1 summarizes the methods used to switch from mode to mode. 



u 



FROM 



TO 






OFF 


C128 


C128 


C64 


CP/M 


CP/M 








40 COL 


80 COL 






40 COL 


80 COL 


CI28 


1 


Check that 




1 


Press ESC 


1 


Check that 


1. Check that 


1. Check that 


40 COL 




40/80 key 






key; 




40/80 key 


40/80 key 


40/80 key 






is UP. 






release. 




is UP. 


is UP. 


is UP. 




2 


Make sure 




2 


Press X 


2 


Turn com- 


2. Turn com- 


2. Turn com- 






that: 






key. 




puter OFF, 


puter OFF, 


puter OFF, 






a)NoCP/M 






OR 




then ON. 


then ON. 


then ON. 






system 




1. 


Check that 


3 


Remove 










disk is 






40/80 key 




cartridge 










in drive 






is UP. 




if present 










b)No C64 




2. 


Press 














cartridge 






RESET 














is in ex- 






button. 














pansion 




















port 


















3. 


Turn com- 
puter ON. 
















CI28 


1. 


Press 


1. Press 






T 


Press 


1. Press 


1. Check that 


80 COL 




40/80 key 


ESC key; 








40/80 key 


40/80 key 


40/80 key 






DOWN. 


release. 








DOWN. 


DOWN. 


is DOWN. 




2. 


Turn com- 


2. Press X 






2. 


Turn com- 


2. Remove 


2. Remove 






puter ON. 


key. 
OR 








puter OFF, 
then ON. 


CP/M sys- 
tem disk 


CP/M sys- 
tem disk 








1. Press 






3. 


Remove 


fi'om 


from 








40/80 key 








cartridge 


drive, if 


drive, if 








DOWN. 








if present. 


necessary. 


necessary. 








2. Press 










3. Turn com- 


3. Turn com- 








RESET 










puter OFF, 


puter OFF, 








button. 










then ON. 


then ON. 



L) 



u 
Ij 
U 



Figure l-l. Commodore 128 Mode Switching Chart 
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Figure l-i. Commodore 128 Mode Switching Chart (continued) 
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COMMODORE 128 



NOTE: If you are using a Commodore 1902 dual monitor, remember to 
move the video switch on the monitor from COMPOSITE or SEPA- 
RATED to RGBI when switching from 40-column to 80-colunm display; 
reverse this step when switching from 80 to 40 columns. Also, when 
switching between modes remove any cartridges from the expansion port. 
You may also have to remove any disk (e.g., CP/M) from the disk drive. 
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CP/M 3.0 SYSTEM RELEASES 



U 



When you send in your CI 28 warranty card, your name will be added to a list 
which makes you eligible for CP/M system release dates. 



HOW TO USE THIS GUIDE 

This guide is designed to be a reference tool that you can consult whenever you need 
detailed technical information on the structure and operation of the Commodore 128 
Personal Computer. Since many of the design features of the Commodore 128 can be 
viewed from various aspects, it may be necessary to consult several different chapters to 
find the information you want. Note that certain groups of chapters form logical sequences 
that cover in detail an extended topic like BASIC, graphics, or machine language. 

The following chapter summaries should help you pinpoint what chapter or 
chapters are most likely to provide the answer to a specific question or problem. 

CHAPTER 2. BASIC BUILDING BLOCKS AND BASIC 7.0 ENCYCLOPEDIA— 
Defines and describes the structural and operational components of the BASIC 
language, including constants, variables and arrays, and numeric and string ex- 
pressions and operations. 

CHAPTER 3. ONE STEP BEYOND SIMPLE BASIC— Provides routines (menu, 
keyboard buffer, loading, prognunming function keys) and techniques ("crunch- 
ing" or saving memory; debugging and merging programs; relocating BASIC) 
that can be incorporated in your own programs. Provides modem-related informa- 
tion (how to generate TouchTone® frequencies, how to detect telephone ringing, 
etc.) plus technical specifications for Commodore Modem/1200 and Modeni/300. 

CHAPTER 4. COMMODORE 128 GRAPHICS PROGRAMMING— Describes the 
general BASIC 7.0 graphics commands (COLOR, GRAPHIC, DRAW, LO- 
CATE, BOX, CIRCLE, PAINT) and gives annotated examples of use, including 
programs. Describes the structure and general function of the color modes and 
character and bit map graphics modes that are fundamental to Commodore 128 
graphics. 
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P 

■J CHAPTER 5. MACHINE LANGUAGE ON THE COMMODORE 128— Defines, 

with examples, machine language (ML) and associated topics, including the 

j~] Kemal; the 8502 registers, binary and hexadecimal numbers, and addressing 

i 1 modes. Defines, with examples, types of ML instructions (op codes, etc.). 

Includes 8502 instruction and addressing table. 

CHAPTER 6. HOW TO ENTER MACHINE LANGUAGE PROGRAMS INTO THE 
COMMODORE 128 — Describes, with examples, how to enter ML programs by 
using the built-in Machine Language Monitor or by POKEing decimal op-code 
values with a BASIC program. Defines, with examples, the ML Monitor commands. 

CHAPTER 7. MIXING MACHINE LANGUAGE AND BASIC— Describes, with 
examples, how to combine BASIC and ML instructions in the same program by 
using BASIC READ, DATA, POKE and SYS commands. Shows where to place 
ML programs in memory. 

CHAPTER 8. THE POWER BEHIND COMMODORE 128 GRAPHICS— Describes 
the CI 28 Mode memory banking concept and tells how to manage banked 
memory. Defines the use of shadow registers. Describes how screen, color and 
character memory are handled in BASIC and machine language, for both character 
and bit map modes. Shows how to redefine the character set. Describes use of 
split-screen modes. Includes a tabular graphics programming summary. 

CHAPTER 9. SPRITES — ^Describes programming of sprites or MOBs (movable object 
blocks). Defines and shows how to use the BASIC 7.0 sprite-related commands 
(SPRITE, SPRDEF, MOVSPR, SSHAPE, GSHAPE, SPRSAV). Provides anno- 
tated examples of use, including programs. 

CHAPTER 10. PROGRAMMING THE 80-COLUMN (8563) CHIP— Defines the 
8563 registers and describes, with machine language examples, how to program 
the 80-column screen in character and bit map modes. 

CHAPTER II. SOUND AND MUSIC ON THE COMMODORE 128— Defines the 
BASIC 7.0 sound and music commands (SOUND, ENVELOPE, VOL, TEMPO, 
PLAY, FILTER). Describes how to code a song in C128 Mode. Defines in detail 
the Sound Interface Device (SID) and how to program it in machine language. 

CHAPTER 12. INPUT/OUTPUT GUIDE— Describes software control of peripheral 
devices connected through I/O ports, including disk drives, printers, other User 
Port and Serial Port devices, the Datassette, and Controller Port devices. Provides 
pin-out diagrams and pin descriptions for all ports. 

CHAPTER 13. THE COMMODORE 128 OPERATING SYSTEM— Describes, with 
examples, the operating system (Kemal), which controls the functioning of the 
Commodore 128; includes the Kemal Jump Table, which lists the ROM entry 
points used to call the Kemal routines; defines each Kemal routine; defines the 
CI 28 Screen Editor. Describes the Memory Management Unit (MMU), defines 
the MMU registers, tells how to select and switch banks in BASIC and ML, and 
tells how to predefine memory configurations. 

CHAPTER 14. CP/M 3.0 ON THE COMMODORE 128— Summarizes the Commo- 
dore version of CP/M 3.0. Defines the general system layout and the operating 
system components (CCP, BIOS and BDOS). Describes the Commodore enhance- 
ments to CP/M 3.0. (Additional details on CP/M 3.0 are given in Appendix K.) 
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CHAPTER 15. COMMODORE 128 AND COMMODORE 64 MEMORY MAPS— U 

Provides detailed memory maps for CI 28 and C64 modes. (The Z80 memory 
map is shown in Appendix K.) I 1 

CHAPTER 1 6. HARDWARE SPECIHCATIONS— Includes technical specifications for LI 

Commodore 128 hardware components (8563, 8564, etc.). 

APPENDIXES A through L — ^Provide additional technical information and/or a more , ^ 

convenient grouping of information supplied elsewhere in the Guide (e.g., pinout 



diagrams). 
GLOSSARY — ^Provides standard definitions of technical terms. 
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The BASIC language is composed of commands, operators, constants, variables, arrays 
and strings. Commands are instructions that the computer follows to perform an 
operation. The other elements of BASIC perform a variety of functions, such as 
assigning values to a quantity, passing values to the computer, or directing the computer 
to perform a mathematical operation. This section describes the structure and functions 
of the elements of the BASIC language. 



COMMANDS AND STATEMENTS 



NUMERIC MEMORY STORAGE: 
CONSTANTS, VARIABLES AND ARRAYS 

There are three ways to store numeric information in Commodore BASIC. The first way 
is to use a constant. A constant is a form of memory storage in which the contents 
remain the same throughout the course of a program. The second type of memory 
storage unit is a variable. As the name indicates, a variable is a memory storage cell in 
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By definition, commands and statements have the following distinctions. A command is 
a BASIC verb which is used in immediate mode. It is not preceded by a program line i~ 

number and it executes immediately after the RETURN key is pressed. A statement is 
a BASIC verb which is contained within a program and is preceded by a line number. 
Program statements are executed with the RUN command followed by the RETURN key. 
Most commands can be used within a program. In this case the command is 
preceded by a line number and is said to be used in program mode. Many commands 
also can be used outside a program in what is called direct mode. For example, LOAD 
is an often-used direct mode command, but you can also include LOAD in a program. ~ 

GET and INPUT are commands that only can be used in a program; otherwise, an _ 

ILLEGAL DIRECT ERROR occurs. While PRINT is usually included within a 
program, you can also use PRINT in direct mode to output a message or numeric value 
to the screen, as in the following example: 

PRINT ' 'The Commodore 128" RETURN 

Notice that the message is displayed on the screen as soon as you press the return i 

key. The following two lines display the same message on the screen. The first line is a 1_ 

program mode statement; the second line is a direct mode command. 

10 PRINT ' 'The Commodore 128"RETURN 

RUN RETURN L 

It is important to know about the concepts behind memory storage before examin- r | 

ing the Commodore BASIC language in detail. Specifically, you need to understand 
constants, variables and arrays. 
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which the contents vary or change throughout the course of a program. The last way to store 
information is to use an array, a series of related memory locations consisting of variables. 
Each of these three units of memory storage can have three different types of 
information or data assigned. The three data types are INTEGER, FLOATING-POINT 
or STRING. Integer data is numeric, whole number data — ^that is, numbers without 
decimal points. Floating-point is numeric data including fractional parts indicated with a 
decimal point. String data is a sequential series of alphanumeric letters, numbers and 
symbols referred to as character strings. The following paragraphs describe these three 
data types and the way each memory storage unit is assigned different data type values. 

CONSTANTS: INTEGER, 
FLOATING-POINT AND STRING 

INTEGER CONSTANTS 

The value assigned to a constant remains unchanged or constant throughout a program. 
Integer constants can contain a positive or negative value ranging from -32768 through 
+ 32767. If the plus sign is omitted, the C128 assumes that the integer is positive. 
Integer constants do not contain commas or decimal points between digits. Leading 
zeros are ignored. Integers are stored in memory as two-byte binary numbers, which 
means a constant requires 16 bits or two bytes of memory to store the integer as a base 
two number. The following are examples of integer constants: 

1 
1000 

-32 



-32767 

FLOATING-POINT CONSTANTS 

Floating-point constants contain fractional parts that are indicated by a decimal 
point. They do not contain commas to separate digits. Floating-point constants may be 
positive or negative. If the plus sign is omitted, it is assumed that the number is 
positive. Again, leading zeros are unnecessary and ignored. Floating-point constants are 
represented in two ways depending on their value: 

1 . Simple Number Notation 

2. Scientific Notation 

In simple number notation, the floating-point number is calculated to ten digits of 
precision and stored using five bytes, but only nine digits are displayed on the screen or 
printer. If the floating-point number is greater than nine digits, it is rounded according to 
the tenth digit. If the tenth digit is greater than five, the ninth digit is rounded to the next 
higher digit. If the tenth digit is less than five, the ninth digit is rounded to the next 
lower digit. The rounding of floating-point numbers may become a factor when calculat- 
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ing values based upon floating-point numbers greater than nine digits. Your program 
should test floating-point results and take them into consideration when basing these 
values on future calculations. 

As mentioned, floating-point numbers are displayed as nine digits. If the value of a 
floating-point constant is less than .01 or greater than 999999999, the number is 
displayed on the screen or printer in scientific notation. For example, the number 
12345678901 is displayed as 1.23456789E+ 10. Otherwise, the simple number notation 
is displayed. A floating-point constant in scientific notation appears in three parts: 



2. The letter E indicates that the number is displayed in exponential (scientific) 
notation. 

3. The exponent specifies the power of ten to which the number is raised and the 
number of places the decimal point is moved in order to represent the number 
in simple number notation. 



SIMPLE NUMBER 


SCIENTIFIC 


9.99 


22.33E + 20 


.0234 


99999.234E-23 


+ 10.01 


-45.89E-11 


-90.23 


-3.14E+17 



NOTE: The values in either column are not equivalent. 



STRING CONSTANTS 

A string constant, as mentioned, is a sequential series of alphanumeric characters 
(numbers, letters and symbols). A string constant can be as long as a 160-character input 



u 



1 . The mantissa is the leftmost number separated by a decimal point. 

The letter E indicates that the number is disDlaved in exnonential fscientifir'* L-i 



u 



The mantissa and exponent can be positive or negative. The exponent can be 
within the range -39 to +38. If the exponent is negative, the decimal point moves to 
the left representing it as a simple number. If the exponent is positive, the decimal 
point moves to the right representing it in simple number notation. | 

The Commodore 128 limits the size of floating-point numbers. The highest L 

number you can represent in scientific notation is 1. 70141 183E + 38. If you try to 
represent a number larger than that, an OVERFLOW ERROR occurs. The smallest s 

number you can represent in scientific notation is 2.93873588E-39. If you try to I 

represent a number smaller than that, no error occurs but a zero is returned as the value. 
You should therefore test floating-point values in your programs if your calculations are 
based on very small numbers and the results depend on future calculations. Here are 
examples of floating-point constants in simple number notation and others in scientific "— 

notation: 
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line, minus the line number and any other information appearing on that program line. 
By concatenating strings together, you may form a string as long as 255 characters. The 
string may contain numbers, letters, and even decimal points and commas. However, 
the string cannot contain the double quote (") character, since this character delimits or 
marks the beginning or ending of the string. You can represent a double quote character 

j— 1 within a string using CHR$(34). You can omit the closing double quote character of a 

] j string if it is the last statement in a line of a program. 

A string can even be assigned a null value, meaning no characters are actually 
assigned to it. Assign a string a null value by omitting characters between the double 

n quotes and follow the opening double quote directly with a closing double quote. Here 

' I are some examples of string constants: 



n 



n 



n 



"Commodore 128" 
"qwerl234!#$%()*.:," 
" " (null string) 
"John and Joan" 

VARIABLES: INTEGER, 
FLOATING-POINT AND STRING 

Variables are units of memory storage that represent varying data values within a 
program. Unlike constants, variables may change in value throughout the course of a 
program. The value assigned to a variable can be an integer, a floating-point number, or 
a string. You can assign a value to a variable as the result of a mathematical calculation. 
Variables are assigned values using an equals sign. The variable name appears to the left 
of the equals sign and the constant or calculation appears to the right. When you refer to 
a variable in a program before you assign it a value, the variable value becomes zero if 
it is an integer or floating-point number. It becomes a null string if the variable is a 
string. 

Variable names can be any length, but for efficiency you should limit the size 
of the variable to a few characters. Only the first two characters of a variable name 
are significant. Therefore, do not begin the names of two different variables with 
the same two characters. If you do, the CI 28 will interpret them as the same variable 
name. 

The first character of a variable name must be a letter. The rest of the 
variable name can be any letter or number from zero to nine. A variable name 
must not contain any BASIC keyword. If you include a BASIC keyword in 
a variable name, a SYNTAX ERROR occurs. BASIC keywords include all 
BASIC statements, commands, function names, logical operator names and reserved 
variables. 

You can specify the data type of a variable by following the variable name with 
a percent sign (%) if the variable is an integer value, or a dollar sign if the 
variable is a string. If no character is specified, the CI 28 assumes that the variable 
value is a floating-point number. Here are some examples of variables and how they are 
assigned: 
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Subscripts are a convenient way to access elements within an array. If subscripts 
did not exist, you would have to assign separate variables for all the data that would 
normally be accessed with a subscript. The first subscript within an array is zero. 

Although arrays are actually stored sequentially in memory, they can be multi- 
dimensional. Tables and matrices are easily manipulated with two-dimensional arrays. 
For example, assume you have a matrix with ten rows and ten columns. You need 100 
storage locations or array elements in order to store the whole matrix. Even though 
your matrix is ten by ten, the elements in the array are stored in memory one 
after the other for 100 hundred locations. 

You specify the number of dimensions in the arrays with the DIM statement. For 
example: 



u 





A = 3.679 (floating-point) 

Z% = 714 (integer) 

F$ = "CELEBRATE THE COMMODORE 128" (string) 

T = A + Z% (floating-point) 

Count % = Count % + 1 (integer) 

G$ = "SEEK A HIGHER LEVEL OF CONSCIOUSNESS" (string) , 

H$ = F$ + G$ (string) I , 

ARRAYS: INTEGER, 

FLOATING-POINT AND STRING L 

• Although arrays were defined earlier in this chapter as series of related variables or 
constants, you refer to them with a single integer, floating point or string variable name. I 

All elements have the same data type as the array name. To access successive elements '^ 

within the array, BASIC uses subscripts (indexed variables) to refer to each unique storage 
compartment in the array. For example, the alphabet has twenty-six letters. Assume an 
array called "ALPHA" is constructed and includes all the letters of the alphabet. To 
access the first element of the array, which is also the first letter of the alphabet (A), 
label Alpha with a subscript of zero: 

ALPHA$(0) A L 

To access the letter B, label Alpha with a subscript of one: 

ALPHA$(1) B L 

Continue in the same manner to access all of the elements of the array ALPHA, as in , 

the following: j 

ALPHA$(2) C , 

ALPHA$(3) D I I 

ALPHA$(4) E '-' 

ALPHA$(5) Z 
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10 DIM A(99) 

dimensions a one-dimensional floating-point array with 100 elements. The following are 
examples of two-, three- and four-dimensional integer arrays: 



20 DIM B(9, 9) (100 elements) 

n 30 DIM C(20,20,20) (9261 elements) 

j j 40DIMD(10,15,15,10) (30976 elements) 

In theory the maximum number of dimensions in an array is 255, but you cannot 

~! fit a DIMension statement that long on a 160-character line. The maximum number of 

I DIMension statements you can fit on a 160-character line is approximately fifty. The 

maximum member of elements allowed in each dimension is 32767. In practice, the size 

1-^ of an array is limited to the amount of available memory. Most arrays are one-, two- or 

I I three-dimensional. If an array contains fewer than ten elements, there is no need for a 

DIM statement since the C128 automatically dimensions variable names to ten elements. 

The first time you refer to the name of the undimensioned array (variable) name, the 

jl C128 assigns zero to the value if it is a numeric array, or a null string if it is a string 

I I array. 

You must separate the subscript for each dimension in your DIMension statement 

nwith a comma. Subscripts can be integer constants, variables, or the integer result of an 
arithmetic operation. Legal subscript values can be between zero and the highest 
dimension assigned in the DIMension statement. If the subscript is referred to outside of 
^ this range, a BAD SUBSCRIPT ERROR results. 

The type of array determines how much memory is used to store the integer, 
floating-point or string data. 

Floating-point string arrays take up the most memory; integer arrays require the 
n least amount of memory. Here's how much memory each type of array requires: 

5 bytes for the array name 
o +2 bytes for each dimension 

j + 2 bytes for each integer array element 

OR -I- 5 bytes for each floating-point element 

nOR + 3 bytes for each string element 
AND + 1 byte per character in each string element 

Keep in mind the amount of storage required for each type of array. If you only 
PI need an integer array, specify that the array be the integer type, since floating-point 

arrays require much more memory than does the integer type. 

Here are some example arrays: 

A$(0) = ' 'GROSS SALES" (string array) 

MTH$(K%) = ' 'JAN' ' (string array) 

G2%(X) = 5 (integer array) 

CNT%(G2%(X)) = CNT%( l)-2 (integer array) 

FP(12*K%) = 24.8 (floating-point array) 
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SUM(CNT%( 1)) = FP*K% (floating-point array) 

A(5) = Sets the 5th element in the 1 dimensional array 

called "A" equal to 

B(5,6) = 26 Sets the element in row position 5 and column 

position 6 in the 2 dimensional array called "B" 
equal to 26 

C( 1,2,3) =100 Sets the element in row position 1, column 

position 2, and depth position 3 in the 3 dimen- 
sional array called "C" equal to 100 



EXPRESSIONS AND OPERATORS 



ARITHMETIC EXPRESSIONS 

Arithmetic expressions yield an integer or floating-point value. The arithmetic operators 
( + ,-,*,/,!) are used to perform addition, subtraction, multiplication, division and 
exponentiation operations, respectively.' 

ARITHMETIC OPERATIONS 

An arithmetic operator defines an arithmetic operation which is performed on the two 
operands on either side of the operator. Arithmetic operations are performed using 
floating-point numbers. Integers are converted to floating-point numbers before an 
arithmetic operation is performed. The result is converted back to an integer if it is 
assigned to an integer variable name. 



u 






n 



Expressions are formed using constants, variables and/or arrays. An expression can be a ^ 

single constant, simple variable, or an array variable of any type. It also can be a 
combination of constants and variables with arithmetic, relational or logical operators ^ 

designed to produce a single value. How operators work is explained below. Expres- 
sions can be separated into two classes: 

1. ARITHMETIC 

2. STRING 

Expressions have two or more data items called operands. Each operand is 
separated by a single operator to produce the desired result. This is usually done by 
assigning the value of the expression to a variable name. 

An operator is a special symbol the BASIC Interpreter in your Commodore 128 
recognizes as representing an operation to be performed on the variables or constant ^ 

data. One or more operators, combined with one or more variables and/or constants 
form an expression. Arithmetic, relational and logical operators are recognized by j ( 

Commodore 128 BASIC. U 
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ADDITION ( + ) 

The plus sign ( + ) specifies that the operand on the right is added to the operand on the 
left. 

EXAMPLES: 

2 + 2 

A + B + C 

X%+1 

BR+lOE-2 

SUBTRACTION (-) 

The minus sign (-) specifies that the operand on the right is subtracted from the operand 



EXAMPLES: 

4-1 
100-64 
A-B 
55-142 



The minus also can be used as a unary minus which is the minus sign in front of a 
negative number. This is equal to subtracting the number from zero (0). 



EXAMPLES: 



-5 

-9E4 

-B 

4-(-2) (same as 4 + 2) 

MULTIPLICATION (*) 

An asterisk (*) specifies that the operand on the left is multiplied by the operand on the 
right. 

EXAMPLES: 

100*2 
50*0 
A*X1 
R%*14 

DIVISION (/) 

The slash (/) specifies that the operand on the left is divided by the operand on the 
right. 
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EXAMPLES: 

10/2 
6400/4 
A/B 
4E2/XR 

EXPONENTIATION ( f ) 

The up arrow ( f ) specifies that the operand on the left is raised to the power specified 
by the operand on the right (the exponent). If the operand on the right is a 2, the number 
on the left is squared; if the exponent is a 3, the number on the left is cubed, etc. The 
exponent can be any number as long as the result of the operation gives a valid 
floating-point number. 

EXAMPLES: 

2 1 2 Equivalent to 2*2 
3 t 3 Equivalent to 3*3*3 
4 1 4 Equivalent to 4*4*4*4 
AB t CD 
3 t -2 Equivalent to '/3*'/3 

RELATIONAL OPERATORS 



< 


LESS THAN 


= 


EQUAL TO 


> 


GREATER THAN 


< = 


LESS THAN OR EQUAL TO 


> = 


GREATER THAN OR EQUAL TO 


<> 


NOT EQUAL TO 


EXAMPLES: 



5-4=1 result true (-1) 

14>66 result false (0) 

15> = 15 result true (-1) 

Relational operators may be used to compare strings. For comparison purposes, 
the letters of the alphabet have the order A<B<C<D, etc. Strings are compared by 
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The relational operators (<, = ,>,< = ,> = ,<>) are primarily used to compare the L 

values of two operands, but they also produce an arithmetic result. The relational 

operators and the logical operators (AND, OR, and NOT), when used in comparisons, r, 

produce an arithmetic true/false evaluation of an expression. If the relationship stated in IJ 

the expression is true, the result is assigned an integer value of -1 . If it's false a value of 

is assigned. Following are the relational operators: - 
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evaluating the relationship between corresponding characters from left to right (see 
string operations). 

EXAMPLES: 

"A" < "B" result true (-1) 
"X" = "YY" result false (0) 
BBS <> CC$ result false (0) if they are the same 

Numeric data items can only be compared (or assigned) with other numeric items. 
The same is true when comparing strings; otherwise, the BASIC error message ?TYPE 
MISMATCH occurs. Numeric operands are compared by first converting the values of 
either or both operands from integer to floating-point form,, as necessary. Then 
the relationship between the floating-point values is evaluated to give a true/false 
result. 

At the end of all comparisons, you get an integer regardless of the data type 
of the operand (even if both are strings). Because of this, a comparison of two 
operands can be used as an operand in performing calculations. The result will 
be -1 or and can be used as anything but a divisor, since division by zero is 
illegal. 



LOGICAL OPERATORS 

The logical operators (AND, OR, NOT) can be used to modify the meaning of the 
relational operators or to produce an arithmetic result. Logical operators can produce 
results other than -1 and 0, although any nonzero result is considered true when testing 
for a true/false condition. 

The logical operators (sometimes called Boolean operators) also can be used to 
perform logical operations on individual binary digits (bits) in two operands. But when 
you're using the NOT operator, the operation is performed only on the single operand to 
the right. The operands must be in the integer range of values (-32768 to + 32767) 
(floating-point numbers are converted to integers) and logical operations give an integer 
result. 

Logical operations are performed bit-by-corresponding-bit on the two operands. 
The logical AND produces a bit result of 1 only if both operand bits are 1 . The logical 
OR produces a bit result of 1 if either operand bit is 1 . The logical NOT is the opposite 
value of each bit as a single operand. In other words, "If it's NOT 1 then it is 0. If it's 
NOT then it is 1." 

The exclusive OR IF (XOR) doesn't have a logical operator but it is performed as 
part of the WAIT statement or as the XOR function. Exclusive-OR means that if the 
bits of two operands are set and equal, then the result is 0; otherwise the result is 1. 

Logical operations are defined by groups of statements which, when taken to- 
gether, constitute a Boolean "truth table" as shown in Table 2-1. 
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The AND operation results in a 1 only if botli bits are 1: 
1 A^fDl = l 

OAP>a)i=o 

1 AND = 

AND 0=0 

Tlie OR operation results in a 1 if either bit is 1: 

1 OR 1 = 1 

OR 1 = 1 

1 OR 0=1 

OR = 

The NOT operation logically complements each bit: 
NOT 1 = 
NOT = 1 

The exclusive OR (XOR) is a tkinction (not a logical operator): 
1XOR1 = 

1 XOR = 1 
XOR 1 = 1 
XOR 0=0 

Table 2-1 Boolean Truth Table 



The logical operators AND, OR and NOT specify a Boolean arithmetic operation 
to be performed on the two operand expressions on either side of the operator. In the 
case of NOT, only the operand on the right is considered. Logical operations (or 
Boolean arithmetic) aren't performed until all arithmetic and relational operations in an 
expression have been evaluated. 

EXAMPLES: 

IF A = 100 AND B = 100 THEN 10 (if both A and B have a value of 100 then 

the result is true) 

A = 96 AND 32: PRINT A (A = 32) 

IF A = 100 OR B = 100 THEN 20 (if A or B is 100 then the result is true) 

A = 64 OR 32: PRINT A (A =96) 

X = NOT 96 (result is -97 (two's complement)) 

HIERARCHY OF OPERATIONS 

All expressions perform the different types of operations according to a fixed hierarchy. 
Certain operations have a higher priority and are performed before other operations. The 
normal order of operations can be modified by enclosing two or more operands within 
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parentheses ( ), creating a "subexpression." The parts of an expression enclosed in pa- 
rentheses will be reduced to a single value before evaluating parts outside the parentheses. 

When you use parentheses in expressions, pair them so that you always have an 
equal number of left and right parentheses. If you don't, the BASIC error message 
7SYNTAX ERROR will occur. 

Expressions that have operands inside parentheses may themselves be enclosed in 
parentheses, forming complex expressions of multiple levels. This is called nesting. 
Parentheses can be nested in expressions to a maximum depth of ten levels — ^ten 
matching sets of parentheses. The innermost expression has its operations performed 
first. Some examples of expressions are: 

A + B 

Ct(D + E)/2 

((X-Cf (D+E)/2)*10) + l 

GG$>HH$ 

JJ$ + "MORE" 

K% = 1 ANDMOX 

K% = 2 OR (A = B AND M<X) 

NOT(D = E) 

The BASIC Interpreter performs operations on expressions by performing arithme- 
tic operations first, then relational operations, and logical operations last. Both arithme- 
tic and logical operators have an order of precedence (or hierarchy of operations) within 
themselves. Relational operators do not have an order of precedence and will be 
performed as the expression is evaluated from left to right. 

If all remaining operators in an expression have the same level of precedence, then 
operations are performed from left to right. When performing operations on expressions 
within parentheses, the normal order of precedence is maintained. The hierarchy of 
arithmetic and logical operations is shown in Table 2-2 from first to last in order of 
precedence. Note that scientific notation is resolved first. 



OPERATOR 


DESCRIPTION 


EXAMPLE 


T 


Exponentiation 


BASE t EXP 


- 


Negation (Unary Minus) 


-A 


*/ 


Multiplication 
Division 


AB*CD 
EF/GH 


+ 


Addition 
Subtraction 


CNT + 2 
JK-PQ 


> = < 


Relational Operations 


A<= B 


NOT 


Logiral NOT 

(Integer Two's Complement) 


NOT K% 


AND 


Logical AND 


JK AND 128 


OR 


Logical OR 


PQ0R15 



Table 2-2 Hierarchy of Operations Performed on Expressions 
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STRING OPERATIONS 

Strings are compared using the same relational operators ( = , <>,< = , > = , <,>) 
that are used for comparing numbers. String comparisons are made by taking one 
character at a time (left-to-right) from each string and evaluating each character 
code position from the character set. If the character codes are the same, the char- 
acters are equal. If the character codes differ, the character with the lower CBM ASCII 
code number is lower in the character set. The comparison stops when the end of either 
string is reached. All other factors being equal, the shorter string is considered less than 
the longer string. Leading or trailing blanks are significant in string evaluations. 

Regardless of the data types, all comparisons yield an integer result. This is 
true even if both operands are strings. Because of this, a comparison of two string 
operands can be used as an operand in performing calculations. The result will i ^ 

be -1 or (true or false) and can be used in any mathematical operation but division I I 

since division by zero is illegal. 

STRING EXPRESSIONS LI 

Expressions are treated as if an implied "<>0" follows them. This means that if an 
expression is true, the next BASIC statement on the same program line is executed. If I 

the expression is false, the rest of the line is ignored and the next line in the program is J 

executed. 

Just as with numbers, you can perform operations on string variables. The only \ j 

arithmetic string operator recognized by BASIC 7.0 is the plus sign (-I-) which is used [j 

to perform concatenation of strings. When strings are concatenated, the string on the 
right of the plus sign is appended to the string on the left, forming a third string. The 
result can be printed immediately, used in a comparison, or assigned to a variable name. j 

If a string data item is compared with (or set equal to) a numeric item, or vice-versa, the ^ 

BASIC error message ?TYPE MISMATCH occurs. Some examples of string expres- 
sions and concatenation are: j j 

10 A$ = "FILE": B$ = "NAME" ^ 

20 NAM$ = A$ -I- B$ (yields the string "HLENAME") 

30 RES$ = "NEW" -I- A$ -I- B$ (yields the string "NEWFILENAME") \ ( 



ORGANIZATION OF THE 
BASIC 7.0 ENCYCLOPEDIA 

This section of Chapter 2 lists BASIC 7.0 language elements in an encyclopedia 
format. It provides an abbreviated list of the rules (syntax) of Commodore 128 
BASIC 7.0, along with a concise description of each. Consult the Commodore 128 
System Guide BASIC 7.0 Encyclopedia (Chapter 5) included with your computer for a 
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more detailed description of each command. BASIC 7.0 includes all the elements of 
BASIC 2.0. 

The different types of BASIC operations are listed in individual sections, as 
follows: 

1. Commands and Statements: the commands used to edit, store and erase 
programs, and the BASIC program statements used in the numbered lines of a 
program. 

2. Functions: the string, numeric and print functions. 

3. Reserved Words and Symbols: the words and symbols reserved for 
use by the BASIC 7.0 language, which cannot be used for any other 
purpose. 



COMMAND AND 
STATEMENT FORMAT 

The command and statement defmitions in this encyclopedia are arranged in the follow- 
ing format: 



Command name — 

Brief definition — 

Command format — 

Discussion of 
format and use — 



EXAMPLES: 

Example(s) — 



AUTO 

Enable/disable automatic line numbering 

AUTO [line#] 

This command turns on the automatic line-numbering feature. 
This eases the job of entering programs, by automatically typing 
the line numbers for the user. As each program line is entered by 
pressing RETURN, the next line number is printed on the screen, 
and the cursor is positioned two spaces to the right of the line 
number. The line number argument refers to the desired incre- 
ment between line numbers. AUTO without an argument turns off 
the auto line numbering, as does RUN. This statement can be 
used only in direct mode (outside of a program). 



AUTO 10 Automatically numbers program lines in incre- 
ments of 10. 

AUTO 50 Automatically numbers lines in increments of 50. 

AUTO Turns off automatic line numbering. 
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The boldface line that defines the format consists of the following elements: 



DLOAD "program name" [,D0,U8] 

T t 

keyword argument additional arguments 

(possibly optional) 



u 






The parts of the command or statement that must be typed exactly as shown are in j { 

capital letters. Words the user supplies, such as the name of a program, are not w^ 

capitalized. 

When quote marks (" ") appear (usually around a program name or filename), the ) ; 

user should include them in the appropriate place, according to the format example. 



LJ 



Keywords are words that are part of the BASIC language. They are the central part of a ^ 

command or statement, and they tell the computer what kind of action to take. )J 

These words cannot be used as variable names. A complete list of reserved words 
and symbols is given at the end of this chapter. 

Keywords, also called reserved words, appear in upper-case letters. Key- | | 

words may be typed using the full word or the approved abbreviation. (A full list "-J 

of abbreviations is given in Appendix I). The keyword or abbreviation must be 
entered correctly or an error will result. The BASIC and DOS error messages are 
defined in Appendices A and B, respectively. 

Arguments, also called parameters, appear in lower-case letters. Arguments comple- 
ment keywords by providing specific information to the command or statement. 
For example, the keyword LOAD tells the computer to load a program while the 
argument "program name" tells the computer which specific program to load. A 
second argument specifies from which drive to load the program. Arguments 
include filenames, variables, line numbers, etc. 

Square Brackets [ ] show optional arguments. The user selects any or none of the 
arguments listed, depending on requirements. 

Angle Brackets <> indicate the user MUST choose one of the arguments listed. 

A Vertical Bar | separates items in a list of arguments when the choices are limited to 
those arguments listed. When the vertical bar appears in a list enclosed in 
SQUARE BRACKETS, the choices are limited to the items in the list, but the 
user still has the option not to use any arguments. If a vertical bar appears within 
angle brackets, the user MUST choose one of the listed arguments. 

Ellipsis ... (a sequence of three dots) means an option or argument can be repeated more 
than once. 

Quotation Marks " " enclose character strings, filenames and other expressions. 
When arguments are enclosed in quotation marks, the quotation marks must be 
included in the command or statement. In this encyclopedia, quotation marks are 
not conventions' used to describe formats; they are required parts of a command or 
statement. 

Parentheses () When arguments are enclosed in parentheses, they must be included in 
the command or statement. Parentheses are not conventions used to describe 
formats; they are required parts of a command or statement. 



n 



i 1 
/ 1 
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Variable refers to any valid BASIC variable names, such as X, A$, T%, etc. 
Expression refers to any valid BASIC expressions, such as A + B + 2,.5*(X + 3), 
etc. 



NOTE: For all DOS commands, variables and expressions used as 
arguments must be endorsed in parentheses. 



BASIC COMMANDS AND 
STATEMENTS 

APPEND 

Append data to the end of a sequential file 

APPEND #logical file number,'Tilenaine"[,Ddrive number][<ON|,>Udevice] 

EXAMPLES: 

Append # 8, "MYFILE" OPEN logical file 8 calted "MYFILE", and prepare 

to append with subsequent PRINT # statements. 

Append #7,(A$),D0,U9 OPEN logical file named by the variable in A$ on 

drive 0, device number 9, and prepare to APPEND. 

AUTO 

Enable/disable automatic line numbering 
AUTO [line#] 

EXAMPLES: 

AUTO 10 Automatically numbers program lines in increments of 10. 
AUTO 50 Automatically numbers lines in increments of 50. 
AUTO Turns off automatic line numbering. 

BACKUP 

Copy the entire contents from one disk to another on a dual disk drive 

BACKUP source Ddrive number TO destination Ddrive number [<ON|,> 
Udevice] 



NOTE: This command can be used only with a dual-disk drive. 
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u 



EXAMPLES: 



u 

BACKUP DO TO Dl Copies all files from the disk in drive to the disk 

in drive 1, in dual disk drive unit 8. i , 

BACKUP DO TO Dl ON U9 Copies all files from drive to drive 1, in disk 

drive unit 9. i i 



BANK 

Select one of the 16 BASIC banks (default memory configurations), numbered 0-15 to 
be used during PEEK, POKE, SYS, and WAIT commands. 

BANK bank number 

Here is a table of available BANK configurations in the Commodore 128 memory: 



BANK CONFIGURATION 

RAM(O) only 

1 RAM(l) only 

2 RAM(2) only (same as 0) 

3 RAM(3) only (same as 1) 

4 Internal ROM , RAM(O), I/O 

5 Internal ROM , RAM(l), I/O 

6 Internal ROM , RAM(2), I/O (same as 4) 

7 Internal ROM , RAM(3), I/O (same as 5) 

8 External ROM , RAM(O), I/O 

9 External ROM , RAM(l), I/O 

10 External ROM , RAM(2), I/O (same as 8) 

11 External ROM , RAM(3), I/O (same as 9) 

12 Kernal and Internal ROM (LOW), RAM(O), I/O 

13 Kernal and External ROM (LOW), RAM(O), I/O 

14 Kernal and BASIC ROM, RAM(O), Character ROM 

15 Kernal and BASIC ROM, RAM(O), I/O 



Banks are described in detail in Chapter 8, The Power Behind Commodore 128 
Graphics and Chapter 13, The Commodore 128 Operating System. 



BEGIN / BEND 

A conditional statement like IF . . . THEN: ELSE, structured so that you can include 
several program lines between the start (BEGIN) and end (BEND) of the structure. 
Here's the format: 



I I 



LJ 
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n 

n 

' IF condition THEN BEGIN : statement 

statement 
Pi statement BEND : ELSE BEGIN 

I 1 statement 

statement BEND 

n EXAMPLE 

10 IF X = 1 THEN BEGIN: PRINT "X = 1 is True" 

20 PRINT "So this part of the statement is performed" 

30 PRINT "When X equals 1" 

40 BEND: PRINT "End of BEGIN/BEND structure":GO to 60 

50 PRINT "X does not equal 1":PRINT "The statements between BEGIN/ 

BEND are slcipped" 

60 PRINT "Rest of Program" 

BLOAD 

Load a binary file starting at the specified memory location 

BLOAD 'Tilename"[,Ddrive number][<ONI,U>device number] [,Bbank 
number] [,Pstart address] 

where: 

■ filename is the name of your file 

■ bank number selects one of the 16 BASIC banks (default memory con- 
figurations) 

■ start address is the memory location where loading begins 

EXAMPLES: 

BLOAD "SPRITES", BO, P3584 LOADS the binary file "SPRITES" 

starting in location 3584 (in BANK 0). 

BLOAD "DATAl", DO, U8, Bl, P4096 LOADS the binary file "DATA 1" 

into location 4096 (BANK 1) from 
Drive 0, unit 8. 

BOOT 

Load and execute a program which was saved as a binary file 

BOOT 'TiIename"[,Ddrive number][<ON|,>Udevice][,Palt LOAD ADD] 

EXAMPLE: 

BOOT BOOT a bootable disk (CP/M Plus for ex- 
ample). 
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BOOT "GRAPHICS 1", DO, U9 LOADS the binary program "GRAPHICS 1" 

from unit 9, drive 0, and executes it. 



BOX 

Draw box at specified position on screen 

BOX [color source], XI, Yl[,X2,Y2][,angle][,paint] 

where: 



1 / 



u 



\ ! 



color source = Background color 

1 = Foreground color (DEFAULT) 
2= Multi-color I 
3 = Multi-color 2 

XI, Yl Comer coordinate (scaled) 

X2,Y2 Comer diagonally opposite XI, Yl, (scaled); default is the PC 
location. 

angle Rotation in clockwise degrees; defauh is degrees 

paint Paint shape with color 
= Do not paint 
1= Paint 
(default = 0) 



EXAMPLES: 

BOX 1, + 10, -I- 10 Draw a box 10 pixels to the right and 10 down from 
the current pixel cursor location. 

BOX 1, 10, 10, 60, 60 Draws the outline of a rectangle. 

BOX , 10, 10, 60, 60, 45, 1 Draws a painted, rotated box (a diamond). 

BOX , 30, 90, , 45, 1 Draws a filled, rotated polygon. 

Any parameter can be omitted but you must include a comma in its place, as in the last 
two examples. 



NOTE: Wrapping occurs if the degree is greater than 360. 



n 
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BSAVE 

Save a binary file from the specified memory locations 

BSAVE "filenaine"[,Ddrive number][<ONI,U>device number] [,Bbank 
nuinber],Pstart address TO Pend address 

where: 

■ start address is the starting address where the program is SAVEd from 

■ end address is the last address + 1 in memory which is SAVEd 

This is similar to the SAVE command in the Machine Language MONITOR. 

EXAMPLES: 

BSAVE "SPRITE DATA",BO, Saves the binary file named "SPRITE DATA", 

P3584 TO P4096 starting at location 3584 through 4095 (BANK 

0). 

BSAVE "PROGRAM.SCR",D0, Saves the binary file named "PROGRAM. 

U9,B0,P3182TOP7999 SCR" in the memory address range 3182 

through 7999 (BANK 0) on drive 0, unit 9. 

CATALOG 

Display the disk directory 

CATALOG [Ddrive number][<ON|,>Udevlce number][,wildcard string] 

EXAMPLE: 

CATALOG Displays the disk directory on drive 0. 

CHAR 

Display characters at the specified position on the screen 

CHAR [color source],X,Y[,string][,RVS] 

This is primarily designed to display characters on a bit mapped screen, but it can also 
be used on a text screen. Here's what the parameters mean: 

color source = Background 
1 = Foreground 

X Character column (0-39) (VIC screen) 
(0-79) (8563) screen 
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Y Character row (0-24) 
string String to print 
reverse Reverse field flag (O=off, 1 =on) 

EXAMPLE: 

10 COLOR 2,3: REM MULTI-COLOR 1 = RED 
20 COLOR 3,7: REM MULTI-COLOR 2 = BLUE 
30 GRAPHIC 3,1 
30 CHAR 0,10,10, "TEXT",0 

CIRCLE 

Draw circles, ellipses, arcs, etc., at specified positions on the screen 
CIRCLE [color source],X,Y[,Xr][,Yr] [,sa][,ea][,angle][,inc] 

where: 



color source 



X,Y 
Xr 
Yr 

sa 

ea 

angle 

inc 



= background color 

1 = foreground color 

2 = multi-color 1 

3 = multi-color 2 

Center coordinate of the CIRCLE 

X radius (scaled); (default = 0) 

Y radius (sealed default is Xr) 

Starting arc angle (default degrees) 

Ending arc angle (default 360 degrees) 

Rotation is clockwise degrees (default is degrees) 

Degrees between segments (default is 2 degrees) 





ea 



EXAMPLES: 

CIRCLEl, 160,100,65,10 Draws an ellipse. 
CIRCLEl, 160,100,65,50 Draws a circle. 



i_j 
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CIRCLEl, 60,40,20,18,,, ,45 Draws an octagon. 

CIRCLEl , 260,40,20,,,,, 90 Draws a diamond. 

CIRCLEl, 60, 140,20,18,,,, 120 Draws a triangle. 

CIRCLE 1 , + 2, + 2,50,50 Draws a circle (two pixels down and two to the 

right) relative to the original coordinates of the 
pixel cursor. 

CIRCLEl, 30;90 Draws a circle 30 pixels and 90 degrees to the 
right of the current pixel cursor coordinate 
position. 

You may omit a parameter, but you must still place a comma in the appropriate 
position. Omitted parameters take on the default values. 

CLOSE 

Close logical file 

CLOSE Hie number 

EXAMPLE: 

CLOSE 2 Logical file 2 is closed. 

CLR 

Clear program variables 
CLR 

CMD 

Redirect screen output to a logical disk or print file. 
CMD logical file number [,write list] 

EXAMPLE: 

OPEN 1 ,4 Opens device 4 (printer). 

CMD 1 All normal output now goes to the printer. 

LIST The LISTing goes to the printer, not the screen — even the word 
READY. 

PRINT#1 Sends output back to the screen. 

CLOSE 1 Closes the file. 
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COLLECT 

Free inaccessible disk space 

COLLECT [Ddrive number][<ON|,>Udevice] 

EXAMPLE: 

COLLECT DO Free all available space which has been incorrectly allocated to 
improperly closed files. Such files are indicated with an asterisk 
on the disk directory. 

COLLISION 

Define handling for sprite collision interrupt | j 

COLLISION type [.statement] 

type Type of interrupt, as follows: 

1 = Sprite-to-sprite collision j 

2 = Sprite-to-display data collision ^ 

3 = Light pen (VIC screen only) 
statement BASIC line number of a subroutine 



EXAMPLE: 



U 



Collision 1 , 5000 Enables a sprite-to-sprite collision and program control sent to 



subroutine at line 5000. y 

Collision 1 Stops interrupt action which was initiated in above example. 

Collision 2, 1000 Enables a sprite-to-data collision and program control directed 
to subroutine in line 1000. 

COLOR 

Define colors for each screen area 

COLOR source number, color number \ 

This statement assigns a color to one of the seven color areas: 



AREA SOURCE { j 

LJ 

40-column (VIC) background 

1 40-coluinn (VIC) foreground 

2 multicolor 1 j 

3 multicolor 2 Lj 

4 40-column (VIC) border 

5 character color (40- or 80-column screen) 

6 80-column background color 



n 
n 
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Colors that are usable are in the range 1-16. 



COLOR CODE 


COLOR 


COLOR CODE 


COLOR 


1 


Black 


9 


Orange 


2 


White 


10 


Brown 


3 


Red 


11 


Light Red 


4 


Cyan 


12 


Darl( Gray 


5 


Purple 


13 


Medium Gray 


6 


Green 


14 


Light Green 


7 


Blue 


15 


Light Blue 


8 


Yellow 


16 


Light Gray 



Color Numbers in 40-Column Output 



1 


Black 


9 


Dark Purple 


2 


White 


10 


Dark Yellow 


3 


Dark Red 


11 


Light Red 


4 


Light Cyan 


12 


Dark Cyan 


5 


Light Purple 


13 


Medium Gray 


6 


Dark Green 


14 


Light Green 


7 


Dark Blue 


15 


Light Blue 


8 


Light Yellow 


16 


Light Gray 



Color Numbers in 80-Column Output 

EXAMPLES: 

COLOR 0, 1: Changes background color of 40-column screen to black. 
COLOR 5, 8: Changes character color to yellow. 



CONCAT 

Concatenate two data files 

CONCAT "file 2" [,Ddrive number] TO "file 1" 
[,Ddrive number][<ON|,>Udevice] 

EXAMPLE: 

Concat "File B" to "File A" FILE B is attached to FILE A, and the combined 

file is designated FILE A. 

Concat (A$) to (B$), Dl, U9 The file named by B$ becomes a new file with 

the same name with the file named by A$ at- 
tached to the end of B$. This is performed on 
Unit 9, drive 1 (a dual disk drive). 
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Whenever a variable is used as a filename, as in the last example, the fllename variable 
must be within parentheses. 

CONT 

Continue program execution 
CONT 

COPY 

Copy a file from one drive to another within a dual disk drive. Copy one file to 
another with a different name within a single drive 

COPY [Ddrive number,]"source fiiename"TO[Ddrive nuinber,]''destination 
filename"[<ON|,>Udevice] 



NOTE: Copying between two single or double disk drive units cannot be 
done. This command does not support unit-to-unit copying. 



EXAMPLES: 

COPY DO, "TEST" TO Dl, "TEST PROG" Copies "test" from drive to drive 

1, renaming it "test prog" on drive 1. 

COPY DO, "STUFF" TO Dl, "STUFF" Copies "STUFF" from drive to 

drive 1. 

COPY DO TO Dl Copies all files from drive to drive 
1. 

COPY "WORK.PROG" TO "BACKUP" Copies "WORK.PROG" as a file 

called "BACKUP" on the same disk 
(drive 0). 

DATA 

Define data to be used by a program 
DATA list of constants 

EXAMPLE: 

DATA 100, 200, FRED, "HELLO, MOM",, 3, 14, ABC123 
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DCLEAR 

Clear all open channels on disk drive 

DCLEAR [Ddrive number][<ON|,>Udevice] 

EXAMPLES: 

DCLEAR DO Clears all open files on drive 0, device number 8. 
DCLEAR D1,U9 Clears all open files (channels) on drive 1, device number 9. 

DCLOSE 

Close disk file 

DCLOSE [#logical file number][<ON|,>Udevice] 

EXAMPLES: 

DCLOSE Closes all channels currently open on unit 8. 

DCLOSE #2 Closes the channel associated with the logical file number 2 on 
unit 8. 

DCLOSE ON U9 Closes all channels currently open on unit 9. 

DEFFN 

Define a user function 

DEF FN name (variable) = expression 

EXAMPLE: 

10 DEF FNA(X) = 12*(34.75-X/.3) + X 
20 PRINT FNA(7) 

The number 7 is inserted each place X is located in the formula given in the DEF 
statement. In the example above, the answer returned is 144. 



NOTE: If you plan to define a function in a program that will use BASIC 
7.0 graphics commands, invoke the GRAPHIC command before defining 
your function. The portion of memory where functions are defined and 
where the graphics screen is located is shared. Once you allocate your 
graphics area, the function definitions are safely placed somewhere else 
in memory. If you don't take this precaution and you invoke the GRAPHIC 
command after you define a function, the function definition (between 
$1C00 and $4000) is destroyed. 
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DELETE 

Delete lines of a BASIC program in the specified range 
DELETE [first line] [-last line] 

EXAMPLES: 

DELETE 75 Deletes line 75. 

DELETE 10-50 Deletes lines 10 through 50, inclusive. 

DELETE-50 Deletes all lines from the beginning of the program up to and 
including line 50. 

DELETE 75- Deletes all lines from 75 to the end of the program, inclusive. 

DIM 

Declare number of elements in an array 

DIM variable (subscripts) [,variable(subscripts)] . . . 

EXAMPLE: 

10 DIM A$(40),B7(15),CC%(4,4,4) 

Dimension three arrays where arrays A$, B7 and CC% have 41 elements, 16 elements 
and 125 elements respectively. 

DIRECTORY 

Display the contents of the disk directory on the screen 

DIRECTORY [Ddrive number][<ON|,>Udevice][,wildcard] 

EXAMPLES: 

DIRECTORY Lists all files on the disk in unit 8. 

DIRECTORY Dl, U9, "WORK" Lists the file named "WORK," on drive 1 of 

unit 9. 

DIRECTORY "AB*" Lists all files starting with the letters "AB" 
like ABOVE, ABOARD, etc. on unit 8. The 
asterisk specifies a wild card, where all files 
starting with "AB" are displayed. 

DIRECTORY DO, "?.BAK" The ? is a wild card that matches any single 

character in that position. For example: FILE 
l.BAK, FILE 2.BAK, FILE 3.BAK all match 
the string. 



u 
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DIRECTORY D1,U9,(A$) 



LISTS the filename stored in the variable A$ 
on device number 9, drive 1 . Remember, when- 
ever a variable is used as a filename, put the 
variable in parentheses. 



NOTE: To print the DIRECTORY of the disk in drive 0, unit 8, use the 
following example: 

LOAD"$0",8 

OPEN4,4:CMD4:LIST 

PRINT#4:CLOSE4 



DLOAD 

Load a BASIC program from the disk drive, device 8. 

DLOAD "filename" [,Ddrive number][<ON|,>Udevice number] 



EXAMPLES: 

DLOAD 



'BANKRECS" 



DLOAD (A$) 



Searches the disk for the program 
and LOADS it. 



'BANKRECS" 



LOADS a program from disk in which the name is 
stored in the variable A$. An error message is given if 
A$ is null. Remember, when a variable is used as a 
filename, it must be enclosed in parentheses. 

DO / LOOP / WHILE / UNTIL / EXIT 

Define and control a program loop 

DO [UNTIL condition | WHILE condition] 

statements [EXIT] 

LOOP [UNTIL condition | WHILE condition] 

This loop structure performs the statements between the DO statement and the LOOP 
statement. If no UNTIL or WHILE modifies either the DO or the LOOP statement, 
execution of the statements in between continues indefinitely. If an EXIT statement is 
encountered in the body of a DO loop, execution is transferred to the first statement 
following the LOOP statement. DO loops may be nested, following the rules defined by 
the FOR-NEXT structure. If the UNTIL parameter is specified, the program continues 
looping until the condition is satisfied (becomes true). The WHILE parameter is the 
opposite of the UNTIL parameter: the program continues looping as long as the 
condition is TRUE. As soon as the condition is no longer true, program control resumes 
with the statement immediately following the LOOP statement. An example of a 
condition (boolean argument) is A = 1, or G>65. 



40 COMMODORE 128 



EXAMPLES: 



10 X = 25 

20 DO UNTIL X = 

30 X = X-1 

40 PRINT "X = ";X 

50 LOOP 

60 PRINT "End of Loop" 



This example performs the statements X = X-1 
and PRINT "X = " ;X until X = 0. When X = the 
program resumes with the PRINT "End of Loop" 
statement immediately following LOOP. 



10 DO WHILE A$<> CHR$ (13):GETKEY A$:PRINT A$:LOOP 

20 PRINT "THE RETURN KEY HAS BEEN PRESSED" 

This DO loop waits for a key to be pressed, 
receives input from the keyboard one character at 
a time and prints the letter of the key which is 
pressed. If the RETURN key is pressed, control is 
transferred out of the loop and line 20 is executed. 



10 DOPEN #8, "SEQFILE" 

20 DO 

30 GET #8,A$ 

40 PRINT A$; 

50 LOOP UNTIL ST 

60 DCLOSE #8 



This program opens file "SEQFILE" and gets 
data until the ST system variable indicates all data 
is input. 



U 



u 

U 



DOPEN 

Open a disk file for a read and/or write operation 

DOPEN # logical file number,"filename[,<type>]"[,Lrecord length] 
[,Ddrive number][<ON|,>Udevice number][,W] 

where type is: 

S = Sequential File Type 
P = Program File Type 
U = User File Type 
R = Relative File Type 

L = Record Length = the length of records in a relative file only 
W = Write Operation (if not specified a read operation occurs) 

EXAMPLES: 

DOPEN# 1 , "ADDRESS" ,W Create the sequential file number 1 (ADDRESS) 

for a write operation 

D0PEN#2 "RECIPES",D1,U9 Open the sequential file number 2 (RECIPES) 

for a read operation on device number 9, drive 1 
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DRAW 

Draw dots, lines and shapes at specified positions on the screen 
DRAW [color source] [,X1, Y1][T0 X2, Y2] . . . 

where: 

Color source = Bit map background 

1 = Bit map foreground 

2 = Multi-color 1 

3 = Multi-color 2 

XI, Yl Starting coordinate (0,0 through 319, 199) 
X2,Y2 Ending coordinate (0,0 through 319,199) 

EXAMPLES: 

DRAW 1, 100,50 Draw a dot. 

DRAW , 10,10 TO 100,60 Draw a line. 

DRAW , 10,10 TO 10,60 TO 100,60 TO 10,10 Draw a triangle. 

DRAW 1 , 120;45 Draw a dot 45° relative and 120 pixels 
away from the current pixel cursor 
position. 

DRAW Draw a dot at the present pixel cursor 
position. Use LOCATE to position the 
pixel cursor. 

You may omit a parameter but you still must include the comma that would have 
followed the unspecified parameter. Omitted parameters take on the default values. 

DSAVE 

Save a BASIC program file to disk 

DSAVE <Tilename" [,Ddrive number][<ON|,>Udevice number] 

EXAMPLES: 

DSAVE "BANKRECS" Saves the program "BANKRECS" to disk. 

DSAVE (A$) Saves the disk program named in the variable A$. 

DSAVE "PROG 3",D1,U9 Saves the program "PR0G3" to disk on unit num- 
ber 9, drive 1. 
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DVERIFY 

Verify the program in memory against the one on disk 

DVERIFY "filename"[,Ddrive number][<ON|,>Udevice number] 

To verify Binary data, see VERIFY "filename", 8,1 format, under VERIFY command 
description. 



END 

Define the end of program execution 
END 



u 



EXAMPLES: 

DVERIFY "C128" Verifies program "C128" on drive 0, unit 8. M 

DVERIFY "SPRITES", D0,U9 Verifies program "SPRITES" on drive 0, de- 
vice 9. , i 



u 



ENVELOPE [ 

Define a musical instrument envelope 

ENVELOPE n[,atk] [,dec] [,sus] [,rei][,wfl [,pw] | 

where: 

n Envelope number (0-9) { 

atk Attack rate (0-15) U 

dec Decay rate (0-15) 
sus Sustain (0-15) , 

rel Release rate (0-15) J 

wf Waveform: = triangle 

1 = sawtooth 

2 = variable pulse (square) 

3 = noise 

4 = ring modulation 
pw Pulse width (0-4095) 

See the "T" option in the PLAY command to select an envelope in a PLAY string. 

EXAMPLE: 

ENVELOPE 1, 10, 5, 10, 0, 2, 2048 This command sets envelope 1 to Attack 

= 10, Decay = 5, Sustain = 10, Release 
= 0, waveform = variable pulse (2), and 
the pulse width = 2048 



n 
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n 

FAST 

n Sets the 8502 microprocessor at a speed of 2MHz. 

FAST 

p This command initiates 2MHz mode, causing the VIC 40-coiumn screen to be turned off. 

j } All operations are speeded up considerably. Graphics may be used, but will not be visible 

until a SLOW command is issued. The Conmiodore 128 powers up in IMHz mode. The 

^ DMA operations (FETCH, SWAP, STASH) must be performed at IMHz (slow) speed. 



n 



FETCH 

Get data from expansion (RAM module) memory 

FETCH #bytes, intsa, expsa, expb 

where bytes = Number of bytes to get from expansion memory (0-65535) where = 
64K (65535 bytes) 
intsa = Starting address of host RAM (0-65535) 
expb = 64K expansion RAM bank number (0-7) where expb = 0-1 for 128K 

and expb = 0-7 for up to 51 2K. 
expsa = Starting address of expansion RAM (0-65535) 
The host BANK for the ROM and I/O configuration is selected with the BANK 
command. The DMA(VIC) RAM bank is selected by bits 6 and 7 of the RAM 
configuration register within the MMU($D506). 

FILTER 

Define sound (SID chip) filter parameters 
FILTER [freq][,lp] [,bp] [,hp] [,res] 

where: 

freq Filter cut-off frequency (0-2047) 

Ip Low-pass filter on (1), off (0) 

bp Band-pass filter on (1), off (0) 

hp High-pass filter on (1), off (0) 

res Resonance (0-15) 

Unspecified parameters result in no change to the current value. 

EXAMPLES: 

FILTER 1024,0,1,0,2 Set the cutoff frequency at 1024, select the band pass 
filter and a resonance level of 2. 

FILTER 2000,1,0,1,10 Set the cutoff frequency at 2000, select both the low 
pass and high pass filters (to form a notch reject) and set 
the resonance level at 10. 
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GET variable list 

EXAMPLE: 

10DO:GETA$:LOOPUNTILA$ = "A" This line waits for the A key to be 

pressed to continue. 



u 





u 



u 



FOR / TO / STEP / NEXT 

Define a repetitive program loop structure. 

FOR variable = start value TO end value [STEP increment] NEXT variable 

The logic of the FOR/NEXT statement is as follows. First, the loop variable is set to the 
start value. When the program reaches a program line containing the NEXT statement, it 
adds the STEP increment (default = 1) to the value of the loop variable and checks to 
see if it is higher than the end value of the loop. If the loop variable is less than or equal 
to the end value, the loop is executed again, starting with the statement immediately 
following the FOR statement. If the loop variable is greater than the end value, the loop 
terminates and the program resumes immediately following the NEXT statement. The 
opposite is true if the step size is negative. See also the NEXT statement. 

EXAMPLE: 

10 FOR L = 1 TO 10 

20 PRINT L 

30 NEXT L 

40 PRINT "I'M DONE! L = "L 

This program prints the numbers from one to 10 followed by the message I'M DONE! 
L = 11. 

EXAMPLE: 

10 FOR L = 1 TO 100 

20 FOR A = 5 TO 11 STEP .5 I 

30 NEXT A U 

40 NEXT L 

The FOR . . . NEXT loop in lines 20 and 30 are nested inside the one in line 10 and 40. J 

Using a STEP increment of .5 is used to illustrate the fact that floating point indices are 
valid. The inner rested loop must lie completely within the outer rested loop (lines 10 
and 40). 

GET 

Receive input data from the keyboard, one character at a time, without waiting for a key |J 

to be pressed. 



u 



u 
u 
u 
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20 GET B, C, D GET numeric variables B,C and D from the keyboard without 
waiting for a key to be pressed. 

' GETKEY 

p* Receive input data from the keyboard, one character at a time and wait for a key to be 

j [ pressed. 

GETKEY variable list 

I I EXAMPLE: 

10 GETKEY A$ 
j This line waits for a key to be pressed. Typing any key continues the program. 

10 GETKEY A$,B$,C$ 
n This line waits for three alphanumeric characters to be entered from the keyboard. 

GET# 

Receive input data from a tape, disk or RS232 
GET# logical file number, variable list 

I I EXAMPLE: 

10 GET#1,A$ This example receives one character, which is stored in the 
PI variable A$, from logical file number 1. This example assumes 

I that file 1 was previously opened. See the OPEN statement. 

^ G064 

I I Switch to C64 mode 

„ G064 

n 

I [ To return to CI 28 mode, press the reset button, or turn off the computer power and 

turn it on again. 

j^ GOSUB 

Call a subroutine from the specified line number 

n GOSUB line number 

I I 

EXAMPLE: 

n 20 GOSUB 800 This example calls the subroutine beginning at line 800 and executes 

M it. All subroutines must terminate with a RETURN statement. 
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800 PRINT "THE C128 WAS WORTH THE WAIT!": RETURN 



GOTO / GO TO 

Transfer program execution to the specified line number 

GOTO line number 
EXAMPLES: 



Q 



10 PRINT"COMMODORE' 
20 GOTO 10 

GOTO 100 



The GOTO in line 20 makes line 10 repeat continu- 
ously until RUN/STOP is pressed. 

Starts (RUNs) the program starting at line 100, 
without clearing the variable storage area. 



u 



GRAPHIC 

Select a graphic mode 

1) GRAPHIC mode [,clear][,s] 

2) GRAPHIC CLR 

This statement puts the Commodore 128 in one of the six graphic modes: 



u 



MODE 


DESCRIPTION 





40-coluinn text (default) 


1 


standard bit-map graphics 


2 


standard bit-map grapliics (split screen) 


3 


multi-color bit-map graphics 


4 


multi-color bit-map graphics (split screen) 


5 


80-column text 



EXAMPLES: 

GRAPHIC 1,1 Select standard bit map mode and clear the bit map. 

GRAPHIC 4,0,10 Select split screen multi-color bit map mode, do not clear the 
bit map and start the split screen at line 10. 

GRAPHIC Select 40-column text. 

GRAPHIC 5 Select 80-column text. 

GRAPHIC CLR Clear and deallocate the bit map screen. 

GSHAPE 

See SSHAPE. 
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HEADER 

Format a diskette 

HEADER "diskname" [,l i.d.] [,Ddrive number] 
[<ON|,>Udevice number] 

Before a new disk can be used for the first time, it must be formatted with the HEADER 
command. The HEADER command can also be used to erase a previously formatted 
disk, which can then be reused. 

When you enter a HEADER command in direct mode, the prompt ARE YOU 
SURE? appears. In program mode, the prompt does not appear. 

The HEADER command is analogous to the BASIC 2.0 command: 

OPEN l,8,15,<'N0:diskname,i.d." 

EXAMPLES: 

HEADER "MYDISK",I23, DO This headers "MYDISK" using i.d. 23 

on drive 0, (default) device number 8. 

HEADER "RECS", 145, Dl ON U9 This headers "RECS" using i.d. 45, on 

drive 1, device number 9. 

HEADER "C128 PROGRAMS", DO This is a quick header on drive 0, device 

number 8, assuming the disk in the drive 
was already formatted. The old i.d. is 
used. 

HEADER (A$),I76,D0,U9 This example headers the diskette with 

the name specified by the variable A$, 
and the i.d. 76 on drive 0, device num- 
ber 9. 

HELP 

Highlight the line where the error occurred 

HELP 

The HELP command is used after an error has been reported in a program. When HELP 
is typed in 40-column format, the line where the error occurs is listed, with the portion 
containing the error displayed in reverse field. In 80-column format, the portion of the 
line where the error occurs is underlined. 

IF / THEN / ELSE 

Evaluate a conditional expression and execute portions of a program depending on the 
outcome of the expression 
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IF expression THEN statements [:ELSE else-clause] 



EXAMPLE: 

50 IF X > THEN PRINT "OK": ELSE END 

This line checks the value of X. If X is greater than 0, the statement immediately 
following the keyword THEN (PRINT "OK") is executed and the ELSE clause is 
ignored. If X is less than or equal to 0, the ELSE clause is executed and the statement 
immediately following THEN is ignored. 

10 IF X = 10 THEN 100 This example evaluates the value of X. 

20 PRINT "X DOES NOT EQUAL 10" IF X equals 10, the program control is 
: transferred to line 100 and the message 



rNPUT 

Receive a data string or a number from the keyboard and wait for the user to press 
RETURN 

INPUT ["prompt string";] variable list 

EXAMPLE: 

10 INPUT "PLEASE TYPE A NUMBER";A 

20 INPUT "AND YOUR NAME";A$ 

30 PRINT A$ " YOU TYPED THE NUMBER"; A 



u 



THE IF . . . THEN statement evaluates a BASIC expression and takes one of two 
possible courses of action depending upon the outcome of the expression. If the 
expression is true, the statement(s) following THEN is executed. This can be any 
BASIC statement or a line number. If the expression is false, the program resumes with 
the program line immediately following the program line containing the IF statement, 
unless an ELSE clause is present. The entire IF . . . THEN statement must be contained 
within 160 characters. Also see BEGIN/BEND. 

The ELSE clause, if present, must be on the same line as the IF . . . THEN 
portion of the statement, and separated from the THEN clause by a colon. When an 
ELSE clause is present, it is executed only when the expression is false. The expression 
being evaluated may be a variable or formula, in which case it is considered true if 
nonzero, and false if zero. In most cases, there is an expression involving relational ] 

operators ( =, <,>, < = ,> = , <>). 



u 



u 
u 



99 STOP "X EQUALS 10" is printed. IF X U 

100 PRINT "X EQUALS 10" does not equal 10, the program resu- 

mes with line 20, the CI 28 prints the 
prompt "X DOES NOT EQUAL 10" 
and the program stops. 



u 
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INPUT # 

Input data from an I/O channel into a string or numeric variable 
INPUT# file number, variable list 

EXAMPLE: 

10 OPEN 2,8,2 

20 INPUT#2, A$, C, D$ 

This statement INPUTs the data stored in variables A$, C and D$ from the disk file 
number 2, which was OPENed in line 10. 

KEY 

Define or list function key assignments 
KEY [key number, string] 

The maximum length for all the definitions together is 241 characters, (p. 3-41) 

EXAMPLE: 

KEY 7, "GRAPHICO" + CHR$(13) + "LIST" + CHR$(13) 

This tells the computer to select the (VIC) text screen and list the program whenever the 
F7 key is pressed (in direct mode). CHR$(13) is the ASCII character for RETURN and 
performs the same action as pressing the RETURN key. Use CHR$(27) for ESCape. 
Use CHR$(34) to incorporate the double quote character into a KEY string. The keys 
may be redefined in a program. For example: 

10 KEY 2,"PRINT DS$" + CHR$(13) 

n This tells the computer to check and display the disk drive error channel variables 

j I (PRINT DS$) each time the F2 function key is pressed. 

10 FOR 1=1 to 7 STEP 2 
P 20 KEY I, CHR$(I + 132):NEXT 

i I 30 FOR 1 = 2 to 8 STEP 2 

40 KEY I, CHR$(I + 132):NEXT 

■"I This defines the function keys as they are defined on the Commodore 64. 

LET 

jj Assigns a value to a variable 

[LET] variable = expression 

rj EXAMPLE: 

10 LET A = 5 Assign the value 5 to numeric variable A. 



1— y 



50 COMMODORE I2B 



20 B = 6 Assign the value 6 to numeric variable B. 

30C = A*B + 3 Assign the numeric variable C, the value resulting from 5 
times 6 plus 3. 

40 D$ = "HELLO" Assign the string "HELLO" to string variable D$. 

LIST 

List the BASIC program currently in memory 
LIST [first line] [- last line] 

In C128 mode, LIST can be used within a program without terminating program execution. 

EXAMPLES: 

LIST Shows entire program. 

LIST 100- Shows from line 100 until the end of the program. 

LIST 10 Shows only line 10. 

LIST - 100 Shows all lines from the beginning through line 100. 

LIST 10-200 Shows lines from 10 to 200, inclusive. 

LOAD 

Load a program from a peripheral device such as the disk drive or Datassette 

LOAD "filename" [,device number] [,relocate flag] 

This is the command used to recall a program stored on disk or cassette tape. Here, the 
filename is a program name up to 16 characters long, in quotes. The name must be 
followed by a comma (outside the quotes) and a number which acts as a device number 
to determine where the program is stored (disk or tape). If no number is supplied, the 
Commodore 128 assumes device number 1 (the Datassette tape recorder). 



EXAMPLES: 



LOAD Reads in the next program from tape. 

LOAD "HELLO" Searches tape for a program called HELLO, and 
LOADS it if found. 

LOAD (A$),8 LOADS the program from disk whose name is 
stored in the variable A$. 

LOAD"HELLO' ' ,8 Looks for the program called HELLO on disk drive 
number 8, drive 0. (This is equivalent to DLOAD 
"HELLO"). 

L0AD"MACHLANG",8,1 LOADs the machine language program called 

"MACHLANG" into the location from which it 
was SAVEd. 
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LOCATE 

i I Position the bit map pixel cursor on the screen 

LOCATE X,Y 

i I The LOCATE statement places the pixel cursor (PC) at any specified pixel coordinate on 

' i the screen. 

The pixel cursor (PC) is the coordinate on the bit map screen where drawing of 
n circles, boxes, lines and points and where PAINTing begins. 

I i 

EXAMPLE: 

j I LOCATE 160,100 Positions the PC in the center of the bit map screen. Noth- 

ing will be seen until something is drawn. 

n LOCATE +20,100 Move the pixel cursor 20 pixels to the right of the last PC 

I 1 position and place it at Y coordinate 100. 

LOCATE -30, + 20 Move the PC 30 pixels to the right and 20 down from the 
|l previous PC position. 

The PC can be found by using the RDOT(O) function to get the X-coordinate and 
Pj RDOT(l) to get the Y-coordinate. The color source of the pixel at the PC can be found 

I I by PRINTing RD0T(2). 

n MONITOR 

^■^ Enter the Commodore 128 machine language monitor 

i I MONITOR 

See Chapter 6 for details on the Commodore 128 Machine Language Monitor. 

MOVSPR 



Position or move sprite on the screen 



p 1) MOVSPR nuinber,X,Y Place the specified sprite at absolute 

sprite coordinate X,Y. 

2) MOVSPR number, +/-X, +/-Y Move sprite relative to the position 

of the sprite's current position. 

3) MOVSPR number,X;Y Move sprite distance X at angle Y 

relative to the sprite's current position. 



52 



COMMODORE 128 



4) MOVSPR number, angle # speed 



Move sprite at an angle relative to 
its current coordinate, in the clock- 
wise direction and at the specified 
speed. 



where: 



number is sprite's number (1 through 8) 
X,Y is coordinate of the sprite location. 

angle is the angle (0-360) of motion in the clockwise direction relative to the 
sprite's original coordinate. 

speed is a speed (0-15) in which the sprite moves. 

This statement moves a sprite to a specific location on the screen according to 
the SPRITE coordinate plane (not the bit map plane) or initiates sprite motion at a 
specified rate. See MOVSPR in Chapter 9 for a diagram of the sprite coordinate 
system. 

EXAMPLES: 

MOVSPR 1,150,150 Position sprite 1 near the center of the screen, x,y 
coordinate 150,150. 

MOVSPR 1,-1-20,-30 Move sprite 1 to the right 20 coordinates and up 30 
coordinates. 

MOVSPR 4, -50, -t- 100 Move sprite 4 to the left 50 coordinates and down 100 

coordinates. 

MOVSPR 5, 45 #15 Move sprite 5 at a 45 degree angle in the clockwise 
direction, relative to its original x and y coordinates. 
The sprite moves at the fastest rate (15). 



NOTE: Once you specify an angle and a speed as in the fourth example 
of the MOVSPR statement, the sprite continues on its path (even if the 
sprite display is disabled) after the program stops, until you set the speed 
to or press RUN/STOP and RESTORE. Also, keep in mind that the 
SCALE command affects the MOVSPR coordinates. If you add SCALing 
to your programs, you also must adjust the sprites' new coordinates so 
they appear correctly on the screen. 
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NEW 

Clear (erase) BASIC program and variable storage 
NEW 



u 
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ON 

Conditionally branch to a specified program line number according to the results of the 
specified expression 

ON expression <GOTO/GOSUB> line #1 [, line #2, . . .] 

EXAMPLE: 

10 INPUT X:IF X<0 THEN 10 

20 ON X GOTO 30, 40, 50, 60 When X = 1 , ON sends control to the first line 

25 STOP number in the list (30). When X = 2, ON sends 

30 PRINT "X = 1" control to the second line (40), etc. 

40 PRINT "X = 2" 

50 PRINT "X = 3" 

60 PRINT "X = 4" 



OPEN 

Open files for input or output 

OPEN logical file number, device number [,secondary address] [<, "filename 
[,filetype[, [mode"]]|<,cmd string>] 



EXAMPLES: 

10 OPEN 3,3 

20 OPEN 1,0 

30 OPEN 1,1,0, "DOT" 

OPEN 4,4 
OPEN 15,8,15 



5 OPEN 8,8,12,"TESTFILE,S,W" 



OPEN the screen as file number 
3. 

OPEN the keyboard as file num- 
ber 1. 

OPEN the cassette for reading, as 
file number 1, using "DOT" as 
the filename. 

OPEN the printer as file number 4. 

OPEN the command channel on 
the disk as file 15, with secondary 
address 15. Secondary address 15 
is reserved for the disk drive error 
channel. 

OPEN a sequential disk file for 
writing called TESTFILE as file 
number 8, with secondary address 
12. 



54 COMMODORE 128 



u 



See also: CLOSE, CMD, GET#, INPUT#, and PRINT# statements and system 
variables ST, DS, and DS$. 

PAINT 

Fill area with color 

PAINT [color source],X,Y[,mode] 

where: 



\ i 

I ' 
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color source = bit map foreground 

1 = bit map background (default) 

2 = multi-color 1 

3 = multi-color 2 

X,Y starting coordinate, scaled (default at pixel cursor (PC)) 

mode = paint an area defined by the color source selected 
1 = paint an area defined by any nonbackground source 

The PAINT command fills an area with color. It fills in the area around the specified 
point until a boundary of the same specified color source is encountered. For example, if 
you draw a circle in the foreground color source, start PAINTing the circle where the 
coordinate assumes the background source. The Commodore 128 will only PAINT 
where the specified source in the PAINT statement is different from the source of the x 
and y pixel coordinate. It cannot PAINT points where the sources are the same in the 
PAINT statement and the specified coordinate. The X and Y coordinate must lie 
completely within the boundary of the shape you intend to PAINT, and the source of the 
starting pixel coordinate and the specified color source must be different. 

EXAMPLE: 

10 CIRCLE 1 , 160, 100,65,50 Draws an outline of a circle. 

20 PAINT 1, 160,100 Fills in the circle with color from source 1 (VIC 

foreground), assuming point 160,100 is colored in 
the background color (source 0). 

Draws an outline of a box. 

Fills the box with color from source 1, assuming 
point 15,15 is colored in the background source 
(0). 

PAINT the screen in the foreground color source 
at the coordinate relative to the pixel cursor's 
previous position plus 10 in both the vertical and 
horizontal positions. 



10 BOX 1, 10, 10, 20, 20 
20 PAINT 1, 15, 15 

30 PAINT 1, + 10, + 10 
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100 PAINT 1, 100;90 Paint the screen area 90° relative to and 100 

pixels away from the current pixel cursor co- 
ordinate. 

PLAY 

Defines and plays musical notes and elements within a string or string variable. 
PLAY "Vn,On,Tn,Un,Xn,elements, notes" 

where the string or string variable is composed of the following 

Vn = Voice (n = 1-3) 

On = Octave (n = 0-6) 

Tn = Tune Envelope Defaults (n = 0-9) 

= piano 

1 = accordion 

2 = calliope 

3 = drum 

4 = flute 
n 5 = guitar 

' 1 6 = harpsichord 

7 = organ 
r~) 8 = trumpet 

i j 9 = xylophone 

Un = Volume (n = 0-8) 
pi Xn = Filter on (n = 1), off(n = 0) 

' ' notes: A,B,C,D,E,F,G 

elements: # Sharp 

$ Flat 

W Whole note 

H Half note 

Q Quarter note 

I Eighth note 

S Sixteenth note 

Dotted 

R Rest 

M Wait for all voices currently playing to end 

the current "measure" 

The PLAY statement gives you the power to select voice, octave and tune envelope 
(including ten predefined musical instrument envelopes), the volume, the filter, and the 
notes you want to PLAY. All these controls are enclosed in quotes. You may include 
spaces in a PLAY string for readability. 

All elements except R and M precede the musical notes in a PLAY string. 
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EXAMPLES: 



PLAY "V1O4T0U5X0CDEFGAB" Play the notes C,D,E,F,G,A and B 

in voice 1 , octave 4, tune envelope 
(piano), at volume 5, with the 
filter off. 

PLAY "V305T6U7X1#B$AW.CHDQEIF" Play the notes B-sharp, A-flat, a 

whole dotted-C note, a half D-note, 
a quarter E-note and an eighth 
F-note. 





u 

II 

! 1 



A$ = ' ' V305T6U3ABCDE' ' : PLAY A$ PLAY the notes and elements within '-' 

A$. 

PLAY "V1CV2EV3G" Plays a chord in the default setting. 1/ 

Change the contents of a RAM memory location tJ 

POKE address, value 

EXAMPLE: LI 

10 POKE 53280, 1 Changes VIC border color 

PRINT 

Output to the text screen 
PRINT [print list] 

The word PRINT can be followed by any of the following: 



\ i 
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Characters inside quotes ("text") 

Variable names (A, B, A$, X$) 

Functions (SIN(23), ABS(33)) ] j 

Expressions (2 + 2),A + 3,A = B) U 

Punctuation marks (;,) 

EXAMPLES: results ! | 

10 PRINT "HELLO" HELLO 

20A$ ="THERE":PRINT"HELLO";A$ HELLO THERE j, 

30 A = 4:B = 2:?A + B 6 U 

40 J = 41:PRINT J;:PRINT J - 1 41 40 

50 PRINT A;B;:D = A + B:PRINT D;A-B 4 2 6 2 

1 I 
See also POS, SPC, TAB and CHAR fiinctions. U 



n 
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PRINT# 

Output data to files 

PRINT# file number[, print list] 

PRINT# is followed by a number which refers to the data file previously OPENed. 

EXAMPLE: 

10 OPEN 4,4 Outputs the data "HELLO THERE" 

20PRINT#4,"HELLOTHERE!",A$,B$ and the variables A$ and B$ to the 

printer. 

10 OPEN 2,8,2 Outputs the data variables A, B$, C 

20 PRINT#2,A,B$,C,D and D to the disk file number 2. 



NOTE: The PRINT# command is used by itself to close the channel to 
the printer before closing the file, as follows: 

10 OPEN 4,4 

30 PRINT#4, "PRINT WORDS" 

40 PRINT#4 

50 CLOSE 4 



PRINT USING 

Output using format 

PRINT [#file number,] USING"format list"; print list 

This statement defines the format of string and numeric items for printing to the text 
screen, printer or other device. 

EXAMPLE: 

5 X = 32: Y = 100.23: A$ = "CAT" 

10 PRINT USING "$##.### ";13.25,X,Y 

20 PRINT USING "###>#";"CBM",A$ 

When this is RUN, line 10 prints: 

$13.25 $32.00 $***** Five asterisks (*****) are printed instead of a Y 

value because Y has five digits, and this condition 
does not conform to format list (as explained below). 

Line 20 prints this: 

CBM CAT Leaves two spaces before printing "CBM" as de- 

fined in format list. 
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The pound sign (#) reserves room for a single character in the output field. If the data I— ' 

item contains more characters than there are # signs in the format field, the entire field 
is filled with asterisks (*): no characters are printed. 



EXAMPLE: 

10 PRINT USING "####";X 

For these values of X, this format displays: 



A = 12.34 


12 


A = 567.89 


568 


A = 123456 


**** 



For a STRING item, the string data is truncated at the bounds of the field. Only as many 
characters are printed as there are pound signs (#) in the format item. Truncation occurs 
on the right. 

EXAMPLES: 



FIELD 


EXPRESSION 


RESULT 


COMMENT 




##.# 


-.1 


-0.1 


Leading zero added. 




##.# 


1 


1.0 


Trailing zero added. 




#### 


-100.5 


-101 


Rounded to no decimal places. 




#### 


-1000 


**** 


Overflow because four digits and a 
cannot fit in field. 


minus sign 


###. 


10 


10. 


Decimal point added. 




#$## 


1 


$1 


Floating dollar sign. 





> 
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PUDEF 

Redefine symbols in PRINT USING statement | j 

PUDEF "nnnn" 

Where "nnnn" is any combination of characters, up to four in all. PUDEF allows you to S I 
redefine any of the following four symbols in the PRINT USING statement: blanks, commas, U 
decimal points and dollar signs. These four symbols can be changed into some other char- 
acter by placing the new character in the correct position in the PUDEF control string. ^ , 

Position 1 is the filler character. The default is a blank. Place a new character here * I 
for another character to appear in place of blanks. 

Position 2 is the comma character. Default is a comma. 

Position 3 is the decimal point. Default is a decimal point. t | 

Position 4 is the dollar sign. Default is a dollar sign. LJ 
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EXAMPLES: 






10 PUDEF"*" 
20 PUDEF" <" 



PRINT * in the place of blanks. 
PRINT < in the place of commas. 



READ 



Read data from DATA statements and input it into a numeric or string variable) 

READ variable list 

This statement inputs information from DATA statements and stores it in variables, 
where the data can be used by the RUNning program. 

In a program, you can READ the data and then re-read it by issuing the 
RESTORE statement. The RESTORE sets the sequential data pointer back to the 
beginning, where the data can be read again. See the RESTORE and DATA statements. 



EXAMPLES: 

10 READ A, B, C 
20 DATA 3, 4, 5 

10 READ A$, B$, C$ 

20 DATA JOHN, PAUL, GEORGE 

10 READ A, B$, C 

20 DATA 1200, NANCY, 345 



READ the first three numeric variables from 
the closest data statement. 

READ the first three string variables from 
the nearest data statement. 

READ (and input into the CI 28 memory) a 
numeric variable, a string variable and an- 
other numeric variable. 



RECORD 

Position relative file pointers 

RECORD# logical file number, record number [,byte number] 

This statement positions a relative file pointer to select any byte (character) of any 
record in the relative file. 

When the record number value is set higher than the last record number in the file, 
the following occurs: 

For a write (PRINT#) operation, additional records are created to expand the file 
to the desired record number. 

For a read (INPUT#) operation, a null record is returned and a "RECORD NOT 
PRESENT ERROR occurs". See your disk drive manual for details about relative 
files. 

EXAMPLES: 

10 D0PEN#2,"FILE" 
20RECORD#2,10,1 
30 PRINT#2,A$ 
40 DCL0SE#2 
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This example opens an existing relative file called "FILE" as file number 2 in LJ 

line 10. Line 20 positions the relative file pointer at the first byte in record number 10. 

Line 30 actually writes the data, A$, to file number 2. | j 

REM 

Comments or remarks about the operation of a program line >' 

REM message 

EXAMPLE: [J 

10 NEXT X:REM THIS LINE INCREMENTS X. 

i 1 

RENAME Li 

Change the name of a file on disk 

RENAME "old filename" TO "new filename" [,Ddrive number][<ONI,> [J 

Udevice number] 



EXAMPLES: 



RENAME "TEST" TO "FINALTEST",D0 Change the name of the file 

"TEST" to "FINAL TEST". 



Li 



LJ 



\ I 

RENAME (A$) TO (B$),D0,U9 Change the filename specified in Lj 

A$ to the filename specified in B$ 
on drive 0, device number 9. Re- ) ) 

member, whenever a variable name 
is used as a filename, it must be 
enclosed in parentheses. 

RENUMBER 

Renumber lines of a BASIC program 

RENUMBER [new starting line number][,increment][,old starting line 
number] 

EXAMPLES: 

RENUMBER Renumbers the program starting at 10, and increments 
each additional line by 10. 

RENUMBER 20, 20, 1 Starting at line 1, renumbers the program. Line 1 be- 
comes line 20, and other lines are numbered in incre- 
ments of 20. 



\ I 



I I 
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RENUMBER,, 65 



Starting at line 65, renumbers in increments of 10. Line 
65 becomes line 10. If you omit a parameter, you must 
still enter a comma in its place. 



RESTORE 



Reset READ pointer so the DATA can be reREAD 

RESTORE [Une#] 

If a line number follows the RESTORE statement, the READ pointer is set to the first 
data item in the specified program line. Otherwise the pointer is reset to the beginning of 
the first DATA statement in the BASIC program. 



EXAMPLES: 



10 FOR I = 1 TO 3 

20 READ X 

30 ALL = X + ALL 

40 NEXT 

50 RESTORE 

60 GOTO 10 

70 DATA 10,20,30 

10 READ A,B,C 
20 DATA 100,500,750 
30 READ X,Y,Z 
40 DATA 36,24,38 
50 RESTORE 40 
60 READ S,P,Q 



This example READs the data in line 70 and stores it in 
numeric variable X. It adds the total of all the numeric 
data items. Once all the data has been READ, three 
cycles through the loop, the READ pointer is RE- 
STOREd to the beginning of the program and it returns 
to line 10 and performs repetitively. 

Line 50 of this example RESTORES the DATA pointer 
to the beginning data item in line 40. When line 60 is 
executed, it will READ the DATA 36,24,38 from line 
40, and store it in numeric variables S, P, and Q, 
respectively. 



RESUME 

Define where the program will continue (RESUME) after an error has been trapped 
RESUME [line number | NEXT] 

This statement is used to restart program execution after TRAPping an error. With no 
parameters, RESUME attempts to re-execute the statement in which the error occurred. 
RESUME NEXT resumes execution at the statement immediately following the one indi- 
cating the error. RESUME followed by a line number will GOTO the specific line and 
resume execution from that line number. RESUME can only be used in program mode. 

EXAMPLE: 

10 TRAP 100 

15 INPUT " ENTER A NUMBER";A 

20 B = 100/A 

40 PRINT'THE RESULT = ";B 
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90 STOP 

100 PRINT "SUBROUTINE 1" 

110 RETURN 



u 



50 INPUT "DO YOU WANT TO RUN IT AGAIN (Y/N)";Z$:IF Z$ = "Y" U 

THEN 10 

60 STOP j I 

100 INPUT"ENTER ANOTHER NUMBER (NOT ZERO)";A [] 

110 RESUME 20 



u 



This example traps a "DIVISION BY ZERO ERROR" in line 20 if is entered in line 
15. If zero is entered, the program goes to line 100, where you are asked to input another 
number besides 0. Line 110 returns to line 20 to complete the calculation. Line 50 asks 
if you want to repeat the program again. If you do, press the Y key. { j 

RETURN 

Return from subroutine ) • 

RETURN 

EXAMPLE: \J 

10 PRINT "ENTER MAIN PROGRAM" 

20 GOSUB 100 I 

30 PRINT "END OF PROGRAM" { 



u 



This example calls the subroutine at line 100 which prints the message "SUBROU- 
TINE 1" and RETURNS to line 30, the rest of the program. ) | 

RUN 

Execute BASIC program 

1) RUN [Une number] 

2) RUN "filename" [,Ddrive number][<ON|,>Udevice number] 

EXAMPLES: 

RUN Starts execution from the beginning of the program. 

RUN 100 Starts program execution at line 100. 

RUN"PRGr' DLOADs "PRGl" from disk drive 8, and runs it from the 
starting line number. 

RUN(A$) DLOADs the program named in the variable A$. 



n 
n 
n 
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SAVE 

Store the program in memory to disk or tape 

SAVE ["fiiename"][,device number][,EOT flag] 

i I EXAMPLES: 

SAVE Stores program on tape, without a name. 

j \ SAVE "HELLO" Stores a program on tape, under the name HELLO. 

I 1 

SAVE A$,8 Stores on disk, with the name stored in variable A$. 



SAVE "HELLO", 8 Stores on disk, with name HELLO (equivalent to 
/ I DS AVE "HELLO"). 

SAVE "HELLO", 1, 2 Stores on tape, with name HELLO, and places an END 
OF TAPE marker after the program. 

SCALE 

Alter scaling in graphics mode 
SCALE n [,Xinax,Yniax] 

where: 

n = 1 (on) or (off) 

Coordinates may be scaled from to 32767 (default = 1023) in both X and Y (in either 
standard or multicolor bit map mode), rather than the normal scale values, which are: 

multi-color mode X = to 159 Y = to 199 
bit map mode X = to 319 Y = to 199 

EXAMPLES: 



10 GRAPHIC 1,1 Enter standard bit map, turn scaling 

^ 20 SCALE LCIRCLE 1,180,100,100,100 on to default size (1023, 1023) and 

i i draw a circle. 

10 GRAPHIC 1,3 Enter multi-color mode, turn scaling 

— 20 SCALE 1,1000,5000 on to size (1000, 5000) and draw a 

j I 30 CIRCLE 1,180,100,100,100 circle. 

The SCALE command affects the sprite coordinates in the MOVSPR command. If 
j I you add scaling to a program that contains sprites, adjust the MOVSPR coordinates 

' I accordingly. 
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SCNCLR 

Clear screen 

SCNCLR mode number 

The modes are as follows: 



MODE NUMBER 


MODE 



1 

2 
3 


40 column (VIC) text 
bit map 

split screen bit map 
multi-color bit map 


4 

5 


split screen multi-color bit map 
80 column (8563) text 



u 



This statement with no argument clears the graphic screen, if it is present, otherwise the j 

nirr«Mit t«»Yt errcfn ic rli^arpH '-^ 



current text screen is cleared. 



EXAMPLES: 



u 



SCNCLR 5 Clears 80 column text screen. 

SCNCLR 1 Clears the (VIC) bit map screen. 

SCNCLR 4 Clears the (VIC) multicolor bit map and 40-column text split screen. 

SCRATCH 

Delete file from the disk directory 

SCRATCH "filename" [,Ddrive number][<ON|,>Udevice number] 

EXAMPLE: [_, 

SCRATCH "MY BACK", DO 

This erases the file MY BACK from the disk in drive 0. 

SLEEP 

Delay program for a specific period of time 

SLEEP N 
where N is seconds 0< N < = 65535. 



! ! 
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SLOW 

Return the Commodore 128 to IMHz operation 
SLOW 

SOUND 

Output sound effects and musical notes 
SOUND v,f,d[,dir][,in][,s][,w][,p] 

where: v = voice (1.. 3) 

f = frequency value (0.. 65535) 

d = duration (0.. 32767) 

dir = step direction (0(up), l(down) or 2(oscillate)) default = 

m = minimum frequency (if sweep is used) (0.. 65535) default = 

s = step value for sweep (0.. 32767) default = 

w = waveform (0 = triangle, 1 = sawtooth, 2 = variable, 3 = noise) 

default = 2 
p = pulse width (0..4095) default = 2048 



EXAMPLES: 



SOUND 1,40960,60 Play a SOUND at frequency 40960 in voice 1 
for 1 second. 



SOUND 2,20000,50,0,2000,100 Output a sound by sweeping through frequen- 
cies starting at 2000 and incrementing upward 
in units of 100 up to 20,000. Each frequency is 
played for 50 jiffies. 

SOUND 3,5000,90,2,3000,500,1 This example outputs a range of sounds start- 
ing at a minimum frequency of 3000, through 
5000, in increments of 500. The direction of 
the sweep is back and forth (oscillating). The 
selected waveform is sawtooth and the voice 
selected is 3. 

SPRCOLOR 

Set multi-color 1 and/or multi-color 2 colors for all sprites 
SPRCOLOR [sincr-l][,smcr-2] 

where: 

smcr-l Sets multi-color 1 for all sprites. 
sincr-2 Sets multi-color 2 for all sprites. 
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Either of these parameters may be any color from 1 through 16. 

EXAMPLES: 

SPRCOLOR 3,7 Sets sprite multi-color 1 to red and multi-color 2 to blue. 
SPRCOLOR 1,2 Sets sprite multi-color 1 to black and multi-color 2 to white. 

SPRDEF 

Enter the SPRite DEFinition mode to create and edit sprite images. 
SPRDEF 

The SPRDEF command defines sprites interactively 

Entering the SPRDEF command displays a sprite work area on the screen which 
is 24 characters wide by 21 characters tall. Each character position in the grid corre- 
sponds to a sprite pixel in the sprite displayed to the right of the work area. Here 
is a summary of the SPRite DEFinition mode operations and the keys that perform 
them: 



u 
u 



u 



u 

u 



USER INPUT 

1-8 

A 

CRSR keys 

RETURN KEY 

RETURN key 

HOME key 

CLR key 

1-4 

CTRL key, 1-8 

Commodore key, 1-8 

STOP key 

SHIFT RETURN 

X 

Y 

M 

C 



DESCRIPTION 

Selects a sprite number at the SPRITE NUMBER? prompt only. 

Turns on and off automatic cursor movement. 

Moves cursor in work/area. 

Moves cursor to start of next line. 

Exits sprite designer mode at the SPRITE NUMBER? prompt 

only. 

Moves cursor to top left comer of sprite work area. 

Erases entire grid. 

Selects color source (enables/disables pixels). 

Selects sprite foreground color (1-8). 

Selects sprite foreground color (9-16). 

Cancels changes and returns to prompt. 

Saves sprite and returns to SPRITE NUMBER? prompt. 

Expands sprite in X (horizontal) direction-. 

Expands sprite in Y (vertical) direction. ' 

Multi-color sprite mode. 

Copies sprite data from one sprite to another. 



u 



SPRITE 

Turn on and off, color, expand and set screen priorities for a sprite 

SPRITE <nuinber> [,on/off|[,fgnd][,priority][,x-exp] [,y-exp][,mode] 

The SPRITE statement controls most of the characteristics of a sprite. 



u 
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PARAMETER DESCRIPTION 

number Sprite number (1-8) 

on/off Turn sprite on (1) or oft (0) 

foreground Sprite foreground color (1-16) (default = sprite number) 

priority Priority is if sprites appear in front of objects on tlie screen. Priority 

is 1 if sprites appear in back of objects on the screen, 

x-exp Horizontal EXPansion on (1) or off (0) 

y-exp Vertical EXPansion on (1) or off (0) 

mode Select standard sprite (0) or multi-color sprite (1) 



n 



n 
n 
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Unspecified parameters in subsequent sprite statements take on the characteristics of the 
previous SPRITE statement. You may check the characteristics of a SPRITE with the 
RSPRITE function. 

EXAMPLES: 

SPRITE 1,1,3 Turn on sprite number 1 and color it red. 

SPRITE 2,1,7,1,1,1 Turn on sprite number 2, color it blue, make it pass 
behind objects on the screen and expand it in the vertical 
and horizontal directions. 

SPRITE 6,1,1,0,0,1,1 Turn on SPRITE number 6, color it black. The first 
tells the computer to display the sprites in front of objects 
on the screen. The second and the 1 following tell the 
CI 28 to expand the sprite vertically only. The last 1 
specifies multi-color mode. Use the SPRCOLOR com- 
mand to select the sprite's multi-colors. 

SPRSAV 

Copy sprite data from a text string variable into a sprite or vice versa, or copy data from 
one sprite to another. 

SPRSAV <origin>,<destination> 

Either the origin or the destination can be a sprite number or a string variable but they 
both cannot be string variables. They can both be sprite numbers. If you are storing a 
string into a sprite, only the first 63 bytes of data are used. The rest are ignored since a 
sprite can only hold 63 data bytes. 

EXAMPLES: 

SPRSAV 1 ,A$ Transfers the image (data) from sprite 1 to the string named A$. 

SPRSAV B$,2 Transfers the data from string variable B$ into sprite 2. 

SPRSAV 2,3 Transfers the data from sprite 2 to sprite 3. 
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SSHAPE / GSHAPE 

Save/retrieve shapes to/from string variables 

SSHAPE and GSHAPE are used to save and load rectangular areas of bit map 
screens to/from BASIC string variables. The command to save an area of the bit map 
screen into a string variable is: 



SSHAPE string variable, XI, Yl [,X2,Y2] 

where: 

string variable String name to save data in 

X1,Y1 Comer coordinate (0,0 through 319,199) (scaled) 
X2,Y2 Comer coordinate opposite (XI, Yl) (default is the PC) 

The command to retrieve (load) the data from a string variable and display it on 
specified screen coordinates is: 

GSHAPE string variable [X,Y][,niode] 

where: 

string Contains shape to be drawn 
X,Y Top left coordinate (0,0 through 3 19, 199) telling where to draw the shape 
(scaled — ^the default is the pixel cursor) 
mode Replacement mode: 

= place shape as is (default) 

1 = invert shape 

2 = OR shape with area 

3 = AND shape with area 

4 = XOR shape with area 

The replacement mode allows you to change the data in the string variable so you can 
invert it, perform a logical OR, exclusive OR (turn off bytes that are on) or AND 
operation on the image. 

EXAMPLES: 

SSHAPE A$,10,10 Saves a rectangular area from the coordinates 10,10 
to the location of the pixel cursor, into string vari- 
able A$. 

SSHAPE B$,20,30,43,50 Saves a rectangular area from top left coordinate 

(20,30) through bottom right coordinate (43,50) into 
string variable B$. 

SSHAPE D$, + 10, + 10 Saves a rectangular area 10 pixels to the right and 

10 pixels down from the current position of the pixel 
cursor. 
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GSHAPE A$, 120,20 Retrieves shape contained in string variable A$ and 
displays it at top left coordinate (120,20). 

GSHAPE B$,30,30,l Retrieves shape contained in string variable B$ and 
displays it at top left coordinate 30,30. The shape is 
inverted due to the replacement mode being selected 
by the 1. 

GSHAPE C$, + 20, + 30 Retrieves shape from string variable C$ and displays 

it 20 pixels to the right and 30 pixels down from the 
current position of the pixel cursor. 



NOTE: Beware using modes 1-4 with multi-color shapes. You may 
obtain unpredictable results. 



STASH 

Move contents of host memory to expansion RAM 

STASH #bytes, intsa, expsa, expb 
Refer to FETCH command for description of parameters. 

STOP 

Halt program execution 
j-] STOP 

! I 

SWAP 

Swap contents of host RAM with contents of expansion RAM 

SWAP #bytes, intsa, expsa, expb 
Refer to FETCH command for description of parameters. 

SYS 

Call and execute a machine language subroutine at the specified address 

SYS address [,a][,x][,y][,s] 

This statement calls a subroutine at a given address in a memory configuration previously 
set up according to the BANK command. Optionally, arguments a,x,y and s are loaded into 
the accumulator, x, y and status registers, respectively, before the subroutine is called. 
The address range is to 65535. The 8502 microprocessor begins executing the 
machine-language program starting at the specified memory location. Also see the 
BANK command. 
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EXAMPLES: 



SYS 32768 Calls and executes the machine-language routine at location 32768 i j 

($8000). y 

SYS 6144,0 Calls and executes the machine-language routine at location 6144 

($1800) and loads zero into the accumulator. i ; 



TEMPO 



u 



Define the speed of the song being played I 

TEMPO n 



where n is a relative duration between (1 and 255) 

The default value is 8, and note duration increases with n. 



u 



EXAMPLES: 

TEMPO 16 Defines the Tempo at 16. 

TEMPO 1 Defines the TEMPO at the slowest speed. 

TEMPO 250 Defines the TEMPO at 250. J 

TRAP 

Detect and correct program errors while a BASIC program is RUNning ^ 

TRAP [line number] 

The RESUME statement can be used to resume program execution. TRAP with no line L 

number turns off error trapping. An error in a TRAP routine cannot be trapped. Also see 
system variables ST, EL, DS and DS$. 



EXAMPLES: 

. 100 TRAP 1000 If an error occurs, GOTO line 1000. 

.1000?ERR$(ER);EL Print the error message, and the error number. 
.1010 RESUME Resume with program execution. 

TROFF 

Turn off error tracing mode 
TROFF 



u 

u 
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TRON 

P] Turn on error tracing 

' ' TRON 
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TRON is used in program debugging. This statement begins trace mode. When you 
RUN the program, the line numbers of the program appear in brackets before any action 
for that line occurs. 

VERIFY 

Verify program in memory against one saved to disk or tape 
VERIFY "filename" [,device number][,relocate flag] 

Issue the VERIFY command immediately after you SAVE a program. 

EXAMPLES: 

VERIFY Checks the next program on the tape. 

VERIFY "HELLO" Searches for HELLO on tape, checks it against memory. 

VERIFY "HELLO", 8,1 Searches for HELLO on disk, then checks it against 

memory. 

VOL 

Define output level of sound for SOUND and PLAY statements 
VOL volume level 

EXAMPLES: 

VOL Sets volume to its lowest level. 
VOL 15 Sets volume for SOUND and PLAY statements to its highest output. 

WAIT 

Pause program execution until a data condition is satisfied 
WAIT <location>, <mask-l> [,mask-2>] 

where: 

location = 0-65535 
masks = 0-255 

The WAIT statement causes program execution to be siispended until a given memory 
address recognizes a specified bit pattern or value. 

The first example below WAITs until a key is pressed on the tape unit to 
continue with the program. The second example will WAIT until a sprite collides with 
the screen background. 
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EXAMPLES: 



WAIT 1, 32, 32 
WAIT 53273, 2 
WAIT 36868, 144, 16 



WIDTH \j 

U 



Set the width of drawn lines 
WIDTH n 



EXAMPLES: 

WIDTH 1 Set single width for graphic commands 
WIDTH 2 Set double width for drawn lines 

WINDOW 

Define a screen window 

WINDOW top left col,top left row,bot right col,bot right row[,clear] 

This command defines a logical window within the 40 or 80 column text screen. The 
coordinates must be in the range 0-39/79 for 40- and 80-column values respectively and 
0-24 for row values. The clear flag, if provided (1), causes a screen-clear to be 
performed (but only within the limits of the newly described window). 

EXAMPLES: 

WINDOW 5,5,35,20 Defines a window with top left comer coordinate as 
5,5 and bottom right comer coordinate as 35,20. 

WINDOW 10,2,33,24,1 Defines a window with upper left comer coordinate 

10,2 and lower right comer coordinate 33,24. Also 
clears the portion of the screen within the window as 
specified by the 1 . 

BASIC FUNCTIONS 






The format of the function description is: 

FUNCTION (argument) j I 

where the argument can be a numeric value, variable or string. '~' 

Each function description is followed by an EXAMPLE. The first line appearing 

below the word "EXAMPLE" is the function you type. The second line without bold is | 

the computer's response. L 
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ABS 

Return absolute value of argument X 
ABS (X) 

EXAMPLE: 

PRINT ABS (7*(-5)) 
35 

ASC 

Return CBM ASCII code for the first character in X$ 

ASC(X$) 
This function returns the CBM ASCII code of the first character of X$. 

EXAMPLE: 

X$ = "C128":PRINT ASC (X$) 
67 

ATN 

Return the arctangent of X in radians 

ATN (X) 
The value returned is in the range - tt/2 through 17/2. 

EXAMPLE: 

PRINT ATN (3) 
1.24904577 

BUMP 

Return sprite collision information 

BUMP (N) 

To determine which sprites have collided since the last check, use the BUMP function. 
BUMP(1) records which sprites have collided with each other, and BUMP(2) records 
which sprites have collided with other objects on the screen. COLLISION need not be 
active to use BUMP. The bit positions (0-7) in the BUMP value correspond to sprites 1 
through 8 respectively. BUMP(n) is reset to zero after each call. 
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Here's how the sprite numbers and BUMP values that are returned correspond: 



u 



BUMP Value: 128 


64 


32 


16 


8 


4 


2 


1 


Sprite Number: 8 


7 


6 


5 


4 


3 


2 


1 



EXAMPLES: 

PRINT BUMP (1) 12 indicates that sprites 3 and 4 have collided. 

PRINT BUMP (2) 32 indicates flie sprite 6 has collided with an object on the screen. 

CHR$ 

Return character for specified CBM ASCII code X 

CHR$(X) 

The argument (X) must be in the range 0-255. This is the opposite of ASC and returns the 
string character whose CBM ASCII code is X. Refer to Appendix E for a table of CHR$ codes. 



Q 



EXAMPLES: U 
PRINT CHR$ (65) Prints the A character. 

PRINT CHR$ (147) Clears the text screen. U 

COS . 

Return cosine for angle of X in radians L 
COS(X) 

EXAMPLE: jj 
PRINT COS (tt/3) 

u 



.5 



FNxx 

Return value from user defined function xx 

FNxx(X) 

This function returns the value from the user defined function xx created in a DEF . 

FNxx statement | 

EXAMPLE: 

10 DEF FNAA(X) = (X-32)*5/9 

20 INPUT X 

30 PRINT FNAA(X) 

RUN 

?40 (? is input prompt) 

4.44444445 
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NOTE: If GRAPHIC is used in a program that defines a function, issue 
the GRAPHIC command before defining the function or the function 
definition is destroyed. 



FRE 

Return number of available bytes in memory 

FRE (X) 

where X is the RAM bank number. X = for BASIC program storage and X = 1 to 
check for available BASIC variable storage. 

EXAMPLES: 

PRINT FRE (0) Returns the number of free bytes for BASIC programs. 
-! 58109 

PRINT FRE (I) Returns the number of free bytes for BASIC variable storage. 
64256 

n HEX$ 

Return hexadecimal string equivalent to decimal number X 

p HEX$(X) 

' EXAMPLE: 

P, PRINT HEX$(53280) 

j I D020 

INSTR 

i ! Return starting position of string 2 within string 1 

INSTR (string 1, string 2 [.starting position]) 

r-i 

I t EXAMPLE: 

PRINT INSTR ("COMMODORE 128", "128") 

1 I 

INT 

n Return integer form (truncated) of a floating point value 

' INT(X) 

r^ This function returns the integer value of the expression. If the expression is positive, 

I I the fractional part is left out. If the expression is negative, any fraction causes the next 

lower integer to be returned. 
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EXAMPLES: 



PRINT INT(-3. 14) 

-4 

JOY 

Return position of joystick and the status of the fire button 
JOY(N) 



EXAMPLES: 

PRINT JOY (2) Joystick 2 fires to the left. 

135 

IF (JOY (1) > 127) THEN PRINT "FIRE" Determines whether the fire button 

is pressed. 

DIR = JOY(l) AND 15 Returns direction (only) of joystick 1. 

LEFT$ 



EXAMPLE: 



PRINT LEFr$("C0MM0D0RE",5) 
COMMO 
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PRINT INT(3. 14) 

3 i 



1 
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when N equals: j / 

1 JOY returns position of joystick 1. —^ 

2 JOY returns postion of joystick 2. 

Any value of 128 or more means that the fire button is also pressed. To find the joystick 
position if the fire button is pressed subtract 128 from the JOY value. The direction is 
indicated as follows. 

u 

8 2 
7 3 . 

6 4 I 

5 ^ 



u 



u 



Return the leftmost characters of string | 

LEFTS (string,integer) 



u 
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LEN 

Return the length of a string 

LEN (string) 
The returned integer value is in the range 0-255. 

EXAMPLE: 

PRINT LEN ("COMMODORE128") 
12 

LOG 

Return natural log of X 



i 1 LOG(X) 



The argument X must be greater than 0. 

EXAMPLE: 

PRINT LOG (37/5) 
2.00148 

MID$ 

Return a substring from a larger string 

MID$ (string,starting position[,length]) 

This function extracts the number of characters specified by length (0-255), from string, 
starting with the character specified by starting position (1-255). 

EXAMPLE: 

PRINT MID$("COMMODORE 128",3,5) 
MMODO 



PEEK 

I j Return contents of a specified memory location 

' ' PEEK(X) 

The data will be returned from the bank selected by the most recent BANK command. 
j j See the BANK command. 

EXAMPLE: 

p 10 BANK 15: VIC = DEC("DOOO") 

j 20 FOR I = 1 TO 47 

' * 30 PRINT PEEK(VIC + I) 

40 NEXT 

I j This example displays the contents of the registers of the VIC chip (some of which 

are ever-changing). 
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EXAMPLES: 

10 PRINT PEN(0);PEN(1) Displays the X and Y coordinates of the light 

pen (for the 40 column screen). 

10 DO UNTIL PEN(4):L00P Ensures that the read values are valid (for the 

80 column screen). 

20 X = PEN(2) 
30 Y = PEN(3) 
40 REM:REST OF PROGRAM 

TT 

Return the value of pi (3.14159265) 

IT 



PRINT IT This returns the result 3. 14159265. 

POINTER 

Return the address of a variable 
POINTER (variable name) 

This function returns a zero if the variable is not defined. 

EXAMPLE: 

A = POINTER (Z) This example returns the address of variable Z. 
NOTE: Address returned is in RAM BANK 1. 







PEN 

Return X and Y coordinates of the light pen \ ( 

PEN(n) ^ 

where n = PEN returns the X coordinate of light pen position on any VIC screen. )~i 

n = 1 PEN retums the Y coordinate of light pen position on any VIC screen. [J 

n = 2 PEN retums the character column position of the 80 column display. 
n = 3 PEN retums the character row position of the 80 column display. 
n = 4 PEN retums the (80-column) light pen trigger value. 



I ( 



The VIC PEN values are not sealed and are taken from the same coordinate plane as 
sprites use. Unlike the 40 column (VIC) screen, the 80 column (8563) coordinates are 
character row and column positions and not pixel coordinates like the VIC screen. Both j I 

the 40 and 80 column screen coordinate values are approximate and vary, due to the 
nature of light pens. The 80-column read values are not valid until PEN(4) is true. 
Light pens are always plugged in to control port 1 . 






u 



EXAMPLE: ) I 








; 1 



n 

n 
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POS 

Return the current cursor column position within the current screen window 

POS(X) 

The POS function indicates where the cursor is within the defined screen window. X is a 
dummy argument, which must be specified, but the value is ignored. The values 
returned range from 0-39 on the VIC screen and 0-79 on the 80-column screen. 

EXAMPLE: 

FOR I = 1 to 10 : ?SPC(I); POS(O): NEXT 

This displays the current cursor position within the defined text window. 

POT 

Returns the value of the game-paddle potentiometer 
I 1 POT(n) 

when: 

i I 

! 1 n = 1, POT returns the position of paddle #1 (control port 1) 

n = 2, POT returns the position of paddle #2 (control port 1) 

f^ n = 3, POT returns the position of paddle #3 (control port 2) 

j I n = 4, POT returns the position of paddle #4 (control port 2) 

,_, The values for POT range from to 255. Any value of 256 or more means that the fire 

! I button is also depressed. 

EXAMPLE: 

j I 10 PRINT POT(l) 

20 IF POT(l) > 256 THEN PRINT "FIRE" 

1^ This example displays the value of game paddle 1 . 

J I 

RCLR 

n 

I j Return color of color source 

RCLR(N) 

I— ( 

I I This function returns the color (1 through 16) assigned to the color source N (0< = N = < 

6), where the following N values apply: 
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SOURCE 


DESCRIPTION 





40-column background 


1 


bit map foreground 


2 


multi-color 1 


3 


multi-color 2 


4 


40-column border 


5 


40- or 80-column character color 


6 


80-column background color 



u 

If 

The counterpart to the RCLR function is the COLOR command. 1 J 

EXAMPLE: 

10 FOR 1 = TO 6 ! I 

20 PRINT "SOURCE";I;"IS COLOR CODE";RCLR(I) "-" 

30 NEXT 



This example prints the color codes for all six color sources. 

ROOT 

Return current position or color source of pixel cursor 
RDOT (N) 

where: 

N = returns the X coordinate of the pixel cursor 
N = 1 returns the Y coordinate of the pixel cursor 
N = 2 returns the color source (0-3) of the pixel cursor 

This function returns the location of the current position of the pixel cursor or the 
current color source of the pixel cursor. 

EXAMPLES: 



y 



1 f 

LJ 



PRINT RDOT(O) Returns X position of pixel cursor H 
PRINT RDOT(l) Returns Y position of pixel cursor 
PRINT RD0T(2) Returns color source of pixel cursor 

RGR ^ 

Return current graphic mode \ ) 

RGR(X) J 

This function returns the current graphic mode. X is a dummy argument, which must be 

specified. The counterpart of the RGR function is the GRAPHIC command. The value I 

returned by RGR(X) pertains to the following modes: '— ' 
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VALUE 


GRAPHIC MODE 


/•^ 






\ 





40 column (VIC) text 


' \ 


1 


Standard bit map 




2 


Split screen bit map 


1-^ 


3 


Multi-color bit map 


1 1 


4 


Split screen Multi-color bit map 




5 


80 column (8563) text 



i I 



I 



EXAMPLE: 



PRINT RGR(O) Displays the current graphic mode; in this case, standard bit 

1 map mode. 

PRINT RGR(O) Both multi-color bit map and 80-column text modes are enabled. 
8 



RIGHT$ 

Return sub-string from rightmost end of string 
RIGHT$(string, numeric) 

EXAMPLE: 

PRINT RIGHT$("BASEBALL",5) 
EBALL 

RND 

Return a random number 
RND (X) 

If X = RND returns a random number based on the hardware clock. 

If X > RND generates a reproducible random number based on the seed 

value below. 
If X < produces a random number which is used as a base called a seed. 

EXAMPLES: 

PRINT RND(O) Displays a random number between and 1. 

.507824123 

PRINT INT(RND(1)*100 -I- 1) Displays a random number between 1 and 100. 
89 
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u 



Q 
U 



RSPCOLOR 

Return sprite multicolor values 

RSPCOLOR (X) 

When: 

X = 1 RSPCOLOR returns the sprite multi-color 1. 
X = 2 RSPCOLOR returns the sprite multi-color 2. 

The returned color value is a value between 1 and 16. The counterpart of the RSPCOLOR 
function is the SPRCOLOR statement. Also see the SPRCOLOR statement. 

EXAMPLE: 

10 SPRITE 1,1,2,0,1,1,1 

20 SPRCOLOR 5,7 

30 PRINT "SPRITE MULTI-COLOR 1 IS";RSPC0L0R(1) 

40 PRINT "SPRITE MULTI-COLOR 2 IS";RSPC0L0R(2) 

RUN 

SPRITE MULTI-COLOR 1 IS 5 
SPRITE MULTI-COLOR 2 IS 7 

In this example line 10 turns on sprite 1, colors it white, expands it in both the X and Y 
directions and displays it in multi-color mode. Line 20 selects sprite multi-colors 1 and 2 
(5 and 7 respectively). Lines 30 and 40 print the RSPCOLOR values for multi-color 1 and 2. 

RSPPOS 

Return the speed and position values of a sprite 

RSPPOS (sprite number ,position|speed) 

where sprite number identifies which sprite is being checked, and position and speed 
specifies X and Y coordinates or the sprite's speed. 
When position equals: 

RSPPOS returns the current X position of the specified sprite. 

1 RSPPOS returns the current Y position of the specified sprite. 

When speed equals: 

2 RSPPOS returns the speed (0-15) of the specified sprite. 

EXAMPLE: : , 

10 SPRITE 1,1,2 U 

20MOVSPR 1,45#13 

30 PRINT RSPPOS ( 1 ,0);RSPPOS ( 1 , 1 );RSPPOS ( 1 ,2) r 

This example returns the current X and Y sprite coordinates and the speed (13). L 







u 





1 1 

i \ 



I 
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RSPRITE 

Return sprite characteristics 

RSPRITE (sprite number,characteristic) 

RSPRITE returns sprite characteristics that were specified in the SPRITE command. 
Sprite number specifies the sprite (1-8) you are checking and the characteristic specifies 
the sprite's display qualities as follows: 





RSPRITE RETURNS 




CHARACTERISTIC 


THESE VALUES: 







Enabled(l) / disabled(O) 




1 


Sprite color (1-16) 




2 


Sprites are displayed in front of (0) or behind 
(1) objects on the screen 




3 


Expand in X direction 


yes = 1, no = 


4 


Expand in Y direction 


yes = 1, no = 


5 


Multi-color 


yes = 1, no = 



EXAMPLE: 

10 FOR I = TO 5 This example prints all 6 characteristics of sprite 1. 

20 PRINT RSPRITE (1,1) 
30 NEXT 

RWINDOW 

Returns the size of the current window or the number of columns of the current 
screen 

RWINDOW (n) 

When n equals: 

RWINDOW returns the number of lines in the current window. 

1 RWINDOW returns the number of rows in the current window. 

2 RWINDOW returns either of the values 40 or 80, depending on the current 
\ screen output format you are using. 

The counterpart of the RWINDOW function is the WINDOW command. 

EXAMPLE: 

10 WINDOW 1,1,10,10 

20 PRINT RWINDOW(0);RWINDOW(1);RWINDOW(2) 

RUN 

9940 

This example returns the lines (10) and columns (10) in the current window. This 
example assumes you are displaying the window in 40 column format. 
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SGN 

Return sign of argument X 
SGN(X) 

EXAMPLE: 

PRINT SGN(4.5);SGN(0);SGN(-2.3) 
1 0-1 

SIN 

Return sine of argument 

SIN(X) 

EXAMPLE: 

PRINT SIN (ir/3) 
.866025404 

SPC 

Skip spaces on printed output 
SPC (X) 

EXAMPLE: 

PRINT "COMMODORE" ;SPC(3);" 128" 
COMMODORE 128 

SQR 

Return square root of argument 



EXAMPLE: 

PRINT SQR(25) 
5 

STR$ 

Return string representation of number 
STR$ (X) 



11 

r 
U 



\ 



SQR (X) U 



u 



u 

u 



M 
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n 



1 1 



EXAMPLE: 

PRINT STR$(123.45) 

123.45 

PRINT STR$(-89.03) 
-89.03 

PRINT STR$(1E20) 
IE + 20 

TAB 

Moves cursor to tab position in present statement 
TAB (X) 

EXAMPLE: 

10 PRINT"COMMODORE"TAB(25)"128" 
COMMODORE 128 

TAN 

Return tangent of argument in radians 

TAN(X) 
This function returns the tangent of X, where X is an angle in radians 

EXAMPLE: 

PRINT TAN(.785398163) 
1 

USR 

Call user-defined subprogram 

USR(X) 

When this function is used, the BASIC program jumps to a machine language program 
whose starting point is contained in memory locations 4633($1219) and 4634($121A), (or 
785($0311) and 786($0312) in C64 mode). The parameter X is passed to the machine- 
language program in the floating-point accumulator ($63-$68 in CI 28 mode). A value is 
returned to the BASIC program through the calling variable. You must direct the value 
into a variable in your program in order to receive the value back from the floating-point 
accumulator. An ILLEGAL QUANTITY ERROR results if you don't specify this 
variable. This allows the user to exchange a variable between machine code and 
BASIC. 
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XOR 

Return exclusive OR value 

XOR (nl,n2) 
This function returns the exclusive OR of the numeric argument values nl and n2. 

X = XOR (nl,n2) 
where nl, n2, are 2 unsigned values (0-65535) 

EXAMPLE: 

PRINT XOR(128,64) 



y 



1/ 

EXAMPLE: U 

10 POKE 4633,0 

20 POKE 4634,48 ^ [ 

30 A = USR(X) i-j 
40 PRINT A 

Place starting location ($3000 = 12288:$00 = 0:$30) = 48 of machine language | j 

routine in location 4633 and 4634. Line 30 stores the returning value from the floating- Lj 
point accumulator. The USER vector is assumed to be in BANK 15. Your machine 

language routine MUST be in RAM bank below address $4000. \ i 

I ( 

VAL 

Return the numeric value of a number string j ( 

VAL(X$) ^ 

EXAMPLE: | i 

10 A$ = "120" U 

20 B$ = "365" 

30 PRINT VAL (A$ + B$) j , 

RUN J! 

485 






192 wj 



RESERVED SYSTEM WORDS 
(KEYWORDS) 

This section lists the words used to make up the BASIC 7.0 language. These words 
cannot be used within a program as other than a component of the BASIC language. The 
only exception is that they may be used within quotes (in a PRINT statement, for example). 



u 
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ABS 


DELETE 


HELP 


POT 


SPRCOLOR 


AND 


DIM 


HEX$ 


PRINT 


SPRDEF 


APPEND 


DIRECTORY 


IF 


PRINT# 


SPRITE 


ASC 


DLOAD 


INPUT 


PUDEF 


SPRSAV 


ATN 


DO 


INPUT# 


(QUIT) 


SQR 


AUTO 


DOPEN 


INSTR 


RCLR 


SSHAPE 


BACKUP 


DRAW 


INT 


RDOT 


ST 


BANK 


DS 


JOY 


READ 


STASH 


BEGIN 


DS$ 


KEY 


RECORD 


STEP 


BEND 


DSAVE 


LEH'$ 


REM 


STOP 


BLOAD 


DVERIFY 


LEN 


RENAME 


STR$ 


BOOT 


EL 


LET 


RENUMBER 


SWAP 


BOX 


ELSE 


LIST 


RESTORE 


SYS 


BSAVE 


END 


LOAD 


RESUME 


TAB 


BUMP 


ENVELOPE 


LOCATE 


RETURN 


TAN 


CATALOG 


ER 


LOG 


RGR 


TEMPO 


CHAR 


ERR$ 


LOOP 


RIGHTS 


THEN 


CHR$ 


EXIT 


MID$ 


RND 


TI 


CIRCLE 


EXP 


MONITOR 


RREG 


TI$ 


CLOSE 


FAST 


MOVSPR 


RSPCOLOR 


TO 


CLR 


FETCH 


NEW 


RSPPOS 


TRAP 


CMD 


FILTER 


NEXT 


RSPRITE 


TROFF 


COLLECT 


FN 


NOT 


RUN 


TRON 


COLLISION FOR 


(OFF) 


RWINDOW 


UNTIL 


COLOR 


FRE 


ON 


SAVE 


USING 


CONCAT 


GET 


OPEN 


SCALE 


USR 


CONT 


GET# 


OR 


SCNCLR 


VAL 


COPY 


G064 


PAINT 


SCRATCH 


VERIFY 


COS 


GOSUB 


PEEK 


SGN 


VOL 


DATA 


GOTO 


PEN 


SIN 


WAIT 


DCLEAR 


GOTO 


PLAY 


SLEEP 


WHILE 


PCLOSE 


GRAPHIC 


POINTER 


SLOW 


WIDTH 


DEC 


GSHAPE 


POKE 


SOUND 


WINDOW 


DEFFN 


HEADER 


POS 


SPC 


XOR 




NOTE: Keywords shown in parentheses are not im 


plemented in C128 






BASIC 7.0. 











Reserved variable names are names reserved for the variables DS, DS$, ER, EL, 
ST, TI and TI$, and the function ERR$. Keywords such as TO and IF or any other 
names that contain keywords, such as RUN, NEW or LOAD cannot be used. 

ST is a status variable for input and output (except normal screen/keyboard 
operations). The value of ST depends on the results of the last I/O operation. In general, 
if the value of ST is 0, then the operation was successful. 
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TI and TI$ are variables that relate to the real time clock built into the Commodore U 

128. The system clock is updated every l/60th of a second. It starts at when the 
Commodore 128 is turned on, and is reset only by changing the value of TI$. The \ j 

variable TI gives the current value of the clock in l/60th of a second. TI$ is a string that jj 

reads the value of the real time clock as a 24-hour clock. The first two characters of TI$ 
contain the hour, the third and fourth characters are minutes and the fifth and sixth 



characters are seconds. This variable can be set to any value (so long as all characters ( 



RESERVED SYSTEM SYMBOLS 

The following characters are reserved system symbols. 



SYMBOL USE(S) 

+ Plus sign Arithmetic addition; string concatenation; relative pixel 

cursor/sprite movement; declare decimal number in ma- 
chine language monitor 
Minus sign Arithmetic subtraction; negative number; unary minus; 

relative pixel cursor/ sprite movement 
* Asterisk Arithmetic multiplication 

/ Slash Arithmetic division 

t Up arrow Arithmetic exponentiation 

Blank space Separate keywords and variable names 

Equal sign Value assignment; relationship testing 

< Less than Relationship testing 

> Greater than Relationship testing 

, Comma Format output in variable lists; command/statement func- 



U 



il 



are numbers) and will be updated automatically as a 24-hour clock. 

EXAMPLE: 

TI$ = "101530" Sets the clock to 10:15 and 30 seconds (AM). '-' 

The value of the clock is lost when the Commodore 128 is turned off. It starts at ^ . 

zero when the Commodore 128 is turned on, and is reset to zero when the value of the j ( 

clock exceeds 235959 (23 hours, 59 minutes and 59 seconds). ^ 

The variable DS reads the disk drive command channel and returns the current 
status of the drive. To get this information in words, PRINT DS$. These status variables 
are used after a disk operation, like DLOAD or DSAVE, to find out why the error light 
on the disk drive is blinking. 

ER, EL and the ERR$ function are variables used in error trapping routines. They ] j 

are usually only useful within a program. ER returns the last error number encountered [J 

since the program was RUN. EL is the line where the error occurred. ERR$ is a 
function that allows the program to print one of the BASIC error messages. PRINT 
ERR$(ER) prints out the proper error message. 



u 



u 



u 



tion parameters [J 
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USE(S) 

Decimal point in floating-point constants 
Format output in variable lists; delimiter 
Separate multiple BASIC statements on a program line 
Enclose string constants 
Abbreviation for the keyword PRINT 
Expression evaluation and ftmctions 
Expression evaluation and functions 
Declare a variable name as integer; declare binary num- 
ber in machine language monitor 
Precede the logical file number in input/output statements 
Declare a variable name as a string and declare hexadeci- 
mal number in machine language monitor 
Declare octal number in machine language monitor 
Declare the numeric constant 3.141592654 





SYMBOL 


• 

9 

( 

) 
% 


Period 
Semicolon 
Colon 

Quotation mark 
Question mark 
Left parenthesis 
Right parenthesis 
Percent 


# 

$ 


Number 
Dollar sign 


& 

IT 


And sign 
Pi 



n 



( 



ii 



( I 



y 



u 



u 



u 



u 



u 



' 1 



/ ! 



; 1 



/ I 



/ 1 

n 

! I 
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ONE STEP 
BEYOND 
SIMPLE BASIC 
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Program 3-1. Menu Skeleton 






Lj 



This chapter takes you one step beyond simple BASIC and presents a collection of useful 
routines. You can incorporate these routines into your own programs as needed. In most 
cases the routines will require only line number changes to be fitted into your programs. \ i 

CREATING A MENU 

A menu is a list of choices you select to perform a specific operation within an ' ' 

application program. A menu directs the computer to a particular part of a program. 
Here is a general example of a menu program: 

5 REM MENU SKELETON '— ^ 

10 SCNCLR 

20 PRINT" 1. FIRST ITEM" 

30 PRINT"2. SECOND ITEM" \ I 

40 PRINT" 3. THIRD ITEM" I t 

50 PRINT"4. FOURTH ITEM" i — ' 

100 PRINT: PRINT" SELECT AN ITEM FROM ABOVE" 

110 GETKEY A5 

120 A=VAL (AS): IF A>4 THEN 10 > | 

130 ON A GOSUB 1000,2000,3000,4000 1 

140 GOTO 10: REM RETURN TO MENU lJ 

999 STOP 

1000 REM START FIRST ROUTINE FOR ITEM ONE HERE 

1999 RETURN i~~", 

2000 REM START SECOND ROUTINE HERE . j 

2999 RETURN M 

3000 REM START THIRD ROUTINE HERE 
39 99 RETURN 

400 REM START FOURTH ROUTINE HERE 
499 9 RETURN 



\ i 

u 



LJ 



The SCNCLR command in line 10 clears the 40-column screen. (Use SCNCLR 
5 if you are using the 80-column screen. The easiest selection is by a number. You may \ i 

use as many selections as can fit on the screen. Line 100 displays a message to the user. jj. 

The GETKEY command in line 1 10 forces the computer to wait for a key to be pressed. 
Since a key represents a character symbol, A$ is a string variable. So that it can be , , 

interpreted as a numeric value in an ON GOTO statement, the string variable is ' ( 

converted to a number with the VAL function in line 120. The IF . . . THEN statement 
in line 120 screens user errors by preventing the user from selecting a number that is not 
in the range of numbers used for choices (4). Line 130 directs control to the appropriate i j 

section (i.e., line number) in your program. Since four selections are offered in this LJ 

example, you must include at least four line numbers. Line 1999 returns to the menu at 
the end of each subroutine that you add at lines 1000, 2000, 3000 and 4000 in the menu \ i 

skeleton. i > 



u 



n 
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BUFFER ROUTINE 



The CI 28 keyboard buffer can hold and dispense up to ten characters from the 
keyboard. This is useful in a word processing program where it is possible at certain 
moments to type faster than the software can actually process. The characters that 
haven't been displayed yet are temporarily stored in the keyboard buffer. The computer 
can hold the next instruction in the buffer for use when the program is ready. This buffer 
allows a maximum of ten characters in queue. To see the buffer in action, enter the 
command SLEEP 5 and immediately press ten different letter keys. After five seconds, 
all ten characters are displayed on the screen. 

Here is a buffer routine that allows you to put items in the keyboard buffer 
from within a program so they are dispensed automatically as the computer is able to act 
upon them. 

In line 10, memory location 208 (198 in C64 mode) is filled with a number 

between and 10 — ^the number of keyboard characters in the keyboard buffer. In line 

p 20, memory locations 842 through 851 (631-640 in C64 mode) are filled with any ten 

, characters you want placed there. In this example, seven characters are in the buffer, 

each a carriage RETURN character. CHR$(13) is the character string code for the 

carriage return character. 

Line 40 places the text "?CHR$(156)" on the screen, but does not execute the 
instruction. Line 50 displays the word "LIST" on the screen. Neither command is 
executed until the program ends. In the CI 28, the keyboard buffer automatically empties 
when a program ends. In this case, the characters in the buffer (carriage return) are 
emptied and act as though you are pressing the RETURN key manually. When this occurs 
on a line where the commands from lines 40 and 50 are displayed, they are executed 
as though you typed them in direct mode and pressed the RETURN key yourself. When 
this program ends, the character color is changed to purple and the program is LISTED 
to the screen. This technique is handy in restarting programs (with RUN or GOTO). 

The next section gives a practical example of using the buffer routine. 

10 POKE 208,7:REM SPECIFY # OF CHARS IN BUFFER 

20 FOR 1=842 TO 849:P0KE I , 13 :NEXT:REM PLACE CHARS IN BUFFER 

30 SLEEP 2 :REM DELAY 

40 SCNCLR: PRINT: PRINT: PRINT: PRINT: PRINT: PRINT: PRINT"? CHRS(156)" 

50 PRINT:PRINT:PRINT:PRINT"LIST":REM PLACE LIST ON SCREEN 

60 PRINT CHR$ (19): PRINT: PRINT :REM GO HOME AND CURSOR DOWN TWICE 

70 REM WHEN PROGRAM ENDS, BUFFER EMPTIES AND EXECUTES 7 RETURNS. 

80 REM THIS CHANGES CHAR COLOR TO PURPLE AND LISTS THE PROGRAM AUTOMATICALLY 

90 REM AS IF YOU PRESSED THE RETURN KEY MANUALLY 

Program 3-2. Buffer Return 

LOADING ROUTINE 

The buffer can be used in automatic loader routines. Many programs often involve the 
loading of several machine code routines as well as a BASIC program. The results of 
the following loader are similar to many found on commercial software packages. 
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2 COLOR 4,1:C0L0R 0,1:COLOR 5,1 

5 A$="PICTURE" 

1 SCNCLR ; PRINT : PRINT : PRINT : PRINT " LOAD" CHR$ ( 3 4 ) ASCHR$ ( 34 ) " , 8 , 1 " 

15 PRINT: PRINT :PRINT"NEW" 

25 BS="FILE3.BIN" 

3 PRINT : PRINT : PRINT ""LOAD"CHR$ ( 34 ) B$CHR$ ( 34 ) " , 8 , 1 " 

45 PRINT: PRINT: PRINT: PRINT: PRINT :PRINT"SYS12*256" 

90 PRINT CHR$(5) :PRINT" GREETINGS FROM COMMODORE" 

100 PRINT" PLEASE STAND BY - LOADING" : PRINT CHR$(144) 

200 PRINT CHR$(19) 

300 POKE208,7:FORI=842TO851:POKEI,13:NEXT 



PROGRAMMING THE 
CI 28 FUNCTION KEYS 

As each of the function keys (Fl through F8) is pressed, the computer displays a BASIC 
command on the screen and in some cases acts immediately. These are known as the 
default values of the function keys. Enter a KEY command to get a list of function key 
values at any time. 



u 
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Program 3-3. Loading Routine j i 



! ) 



u 



Line 2 colors the border, screen and characters black. Line 5 assigns A$ the 
filename "PICTURE", which in this example assumes that it is an 8K binary file of a 
bit-mapped screen. Line 10 places the LOAD instruction for the picture file on the i— ' 

screen, but does not execute it. A carriage return from the keyboard buffer executes the 
load instruction once the program ends and the keyboard buffer empties. Line 15 prints 
the word "NEW" on the screen. Again, this operation is not carried out until a carriage 
return is executed on the same line once the keyboard buffer empties. After loading a 
machine language program, a NEW is performed to set pointers to their original 
positions and clear the variable storage area. Line 30 displays the second load instruc- 
tion for the machine language program "FILE3.BIN". This hypothetical program 
enables the bit mapped PICTURE, and anything else you want to supply in the program. 
Line 45 initiates (SYS 12*256), the "FILE3.BIN" program starting at 3072 ($0C00) 
once the keyboard buffer empties. This is only a template sample for you to follow. 
"PICTURE" and "FILE3.BIN" are programs you supply and are only used to illustrate 
one technique of automatic loading. Since the previous character color was black, all the 
loading instructions are displayed in black on a black background, so they can't be seen. 
The CHR$(5) in line 90 changes the character color to white, so the only visible 
messages are the ones in white in lines 90 and 100, while the disk drive is loading 
"PICTURE" and "FILE3.BIN". Line 300 is the buffer routine. 

If you were to do each step manually it would require seven "RETURNS". This 
program places seven carriage return characters in the keyboard buffer, and they are 
dispensed automatically when the program ends. As each RETURN is accepted, the 
corresponding screen instruction is enacted automatically as if you had pressed the 
RETURN key manually. 
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CHANGING FUNCTION KEYS 

You can change the value assigned to any function key by entering the KEY command 
followed by the number (1 through 8) of the key you want changed, a comma, and the 
new key instruction in a string format. For example: 

KEYl, "DLOAD" + CHR$(34)+ "PROGRAM NAME" 
+ CHR$(34) + CHR$(13)+ "LIST" + CHR$(13) 



This tells the computer to automatically load the BASIC program called "program 
_ name" and list it immediately (whenever Fl is pressed). The character string code value 

I ' for the quote character is 34. It is necessary for LOAD and SAVE operations. The 

character string code value for RETURN is 13 and provides immediate execution. 
Otherwise, the instruction is only displayed on the screen and requires you to supply the 
additional response and press the RETURN key. 

The following example uses the ASCII value for the ESCape key to assign the F3 
key to cause a downward scroll: 

KEY3,CHR$(27) + "W" 



NOTE: All eight KEY definitions in total must not exceed 246 characters. 



USING C64 FUNCTION KEY VALUES 
IN CI 28 NODE 

Programs previously written for the C64 which incorporate the function keys may still 
be used in C128 mode by first assigning the C64 ASCII values to them with this 
instruction: 

lOJ = 132:FORA = 1T02:F0RK = AT08STEP2:J = J + 1 :KEYK,CHR$(J):NEXT: 
NEXT 



HOW TO CRUNCH BASIC PROGRAMS 

Several techniques known collectively as memory crunching allow you to get the most 
out of your computer's memory. These techniques include eliminating spaces, using 
multiple instructions, having syntax relief, removing remark statements, using variables, 
and in general using BASIC intelligently. 

ELIMINATING SPACES 

In most BASIC commands, spacing is unnecessary, except inside quotes when you want 
the spaces to appear on the screen. Although spaces improve readability, the extra space 
consumes additional memory. Here is an instructional line presented both ways: 

10INPUT"FIRST NAME";N$:FOR T = A TO M:PRINT "OK": 

lOINPUT' 'FIRST NAME' ' ;N$:FORT = ATOM:PRINT' 'OK" : 
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USING MULTIPLE INSTRUCTIONS 

Colons allow you to place several instructions within a single program line. Each 
program line consumes additional memory. Be careful, however, crunching IF state- 
ments. Any instruction after the IF statement with the same line number can be bypassed 
along with the IF . . . THEN condition. The following line is the equivalent of five 
lines: 

(A) 
10 FRINTX:INPUTY:PRINTY:SCNCLRO:?J 

(B) 
10 PRINTX 
20 INPUTY 
30 PRINTY 
40 SCNCLRO 
50 PRINTJ 

Example A requires less space in memory and on disk. Example B requires 16 
additional bytes; 2 bytes for each additional line number and 2 bytes for the link to the 
next line number. 

SYNTAX RELIEF 

Some BASIC syntax is very flexible and this flexibility can be used to your advantage. 
The LET statement, for example, can be written without LET. LET Y= 2 is the same as 
Y = 2. Although it is good practice to initialize all variables to zero, it is not necessary 
since the computer automatically sets all variables to zero, including subscripted vari- 
ables. DIMension all arrays (subscripted variables) to have twelve or more elements. The 
CI 28 automatically dimensions each variable to have eleven subscripted elements if no 
dimension is specified following DIM and the variable names. Often semicolons are not 
required in PRINT statements. Both of these perform the same results: 

10 PRINT"A";Z$;"WORD";CHR$(65);"NOW $" 
20 PRINT"A"Z$"WORD"CHR$(65)"NOW $" 

REMOVING REM STATEMENTS 

Although REM statements are useful to the programmer, removing them makes a 
considerable amount of memory available again. It might be a good idea to create a 
separate listing with REM statements. 

USING VARIABLES 

Replace repeated numbers with a variable. This is especially important with large 
numbers such as memory addresses. POKEing several numbers in sequence conserves 
memory if a variable is used, such as POKE 54273 + V, etc. Of course, single-letter 
variable names require the least memory. Reuse old variables such as those used in FOR 
. . . NEXT loops. Whenever possible, make use of integer variables since they consume 
far less memory than floating-point variables. 
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USING BASIC INTELLIGENTLY 

If information is used repeatedly, store the data in integer arrays, if possible. Use DATA 
jj statements where feasible. Where a similar line is used repeatedly, create a single line 

' I with variables and access it with GOSUBs. Use TAB and SPC functions in place of 

extensive cursor controls. 



MASKING BITS 

Any of the bits within a byte can be controlled individually, using the Boolean operators 
AND and OR. Calculations with AND and OR are based on a truth table (Table 3-1) 
showing the results given all possible true and false combinations of the arguments X and Y. 



X Y 


XANDY 


XORY 











1 





1 


1 





1 


1 1 


1 


1 



Table 3-1. AND and OR Truth Table 



With "0" representing False and "1" Truth, Table 3-1 shows how the operators 
AND and OR work. The result of an AND operation between two bits is only true if 
both bits are true (1). Otherwise the combination is false. Any bit combination with a 
zero yields a zero in an AND operation. The result of an AND operation is only true 
(equal to 1) if both bits are true (equal to 1). 

The result of an OR operation is only false if each bit is false. Otherwise the result 
is true. Any bit combination with a one yields a one in an OR operation. ONLY two 
zeros result in a zero. 

Observe the following example with the numbers 5 and 6 in binary form. When 
you type the command PRINT 5 AND 6, the result is 4. Here's why: 

5= 0000 0101 
6= 0000 0110 



ANDed 4= 0000 0100 



Instead of adding, ANDing performs a bit-by-bit comparison in accordance with 
the rules of the AND truth table. Compare column-for-column from the right: 1 AND 
= 0, AND 1 = 0, 1 AND 1 = 1, AND = 0. The result "0100" converted to 
decimal is the number 4. 

What is the effect of ORing 5 and 6? Again comparing bit-by-bit, using the rules 
from the OR truth table: 
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5= 0000 0101 
6= 0000 0110 



ORing 7= 0000 0111 



The result 0111 is decimal 7. Notice from the right that 1 OR 0= 1, OR 1 = 1, 1 OR 
1 = 1 and OR = 0. 

Understanding how these OR and AND combinations work gives you the power to 
control individual bits within your computer's memory. Many of the 8-bit bytes utilize 
each bit for separate control parameters. 

USING OR AND AND TO MODIFY 
THE BIT VALUES IN A BYTE 

A byte is a group of eight binary digits labeled, from right to left, to 7. Each binary 
digit position represents a decimal value equal to two raised to the power of the position 
number. For example, the decimal value of position 6 is 2**6 or 64. From left to right 
the positions are: 

7 6 5 4 3 2 10 

and the corresponding values in decimal are: 

128 64 32 16 8 4 2 1 

To turn on a bit, place a "1" in its position. To turn it off, enter a "0". Hence the 
binary 10010000 has bits 4 and 7 on. Their values are 128 and 16. So if a particular byte 
is POKED with 144 (128+16), these two bits are turned on. To turn bits on, store 
(POKE) a new value to that byte — a value equal to the sum of all the decimal 
equivalents of all the bits that are enabled (on). Of course, you do not always know 
which bits are ahready on. You may only want to turn on specific bits without 
affecting the others. That's the purpose of the logical operations AND and OR. 

First, obtain the decimal value of the byte by PEEKing. Then add the decimal 
value of the bit you wish to turn on. The following command turns on bit 2 of memory 
address "V": 

POKEV, PEEK(V) + 4 

This assumes bit 2 (third bit from the right) had a value of 0. Had it already been 
"on," it would have no effect. To prevent such confusion, the C128 uses the power of 
Boolean Logic. 

Ideally you want to read (PEEK) each bit. The proper approach is to OR the byte 
with an operand byte which will yield the desired binary value. Suppose we want to 
turn on bit 5; the operand byte becomes 00100000. By ORing this with any byte it will 
affect only bit 5, because any combination involving 1 in an OR operation results in 1. 
Thus no bit already ON can be inadvertently turned off. 

POKEV,PEEK(V) OR 32 

Just as OR turns a switch on, AND can turn a switch off— with a slight difference. 
AND results in a "1" only if both bits compared are "1." The trick is to compare the 
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byte in question with an operand byte of all ON bits except the bit you want turned off. 
Bits to remain on will not be affected. To turn off bit 5, AND the byte in question with 
the mirror image of 00100000 or the operand byte 11011111. In decimal this value is 
always 255 minus the value of the bit(s) you want to turn off. Thus: 

POKEV,PEEK(V) AND (255-32) 

turns off bit 5. 

Use OR to turn bits ON 
Use AND to turn bits OFF 

EXAMPLES: 

POKEW,PEEK(W) OR 129 Turns ON bits and 7 of memory address W. 

POKES, PEEK(S) AND 126 Turns OFF bits and 7 of memory register S 

(Remember 255-129 = 126) 

POKEC,PEEK(C)AND254 Turns OFF bit 

POKEC,PEEK(V)OR63 Turns ON all bits except 6 and 7 

DEBUGGING PROGRAMS 

No program when first written is free of "bugs" or errors. The process of finding errors 
and removing them, debugging, combines editing with problem solving. 

SYNTAX ERRORS 

Syntax errors result from misspelling or misusing the guidelines and formats of BASIC 
commands. An error message is displayed on the screen defining the line where the 
error occurs. Typing HELP <RETURN> or pressing the HELP key also highlights the 
line with the error. Common syntax errors include misspelled BASIC terms, misplaced 
punctuation, unpaired parentheses, reserved variable names such as TI$, use of line 
numbers that do not exist, etc. 

LOGIC ERRORS 

Sometimes errors exist in the program logic, with the result that the program doesn't do 
exactly what you think it is supposed to do. Some logic errors are caused by the order of 
instructions. One common fault occurs when you forget that anything on a line after an 
IF statement is affected by the IF condition. 

Some errors in logic require a trial-and-error investigation. This is best initiated by 
asking the computer for help in BASIC. 

USING A DELAY 

Where the computer responds rapidly, it often helps to see a response by inserting a 
SLEEP command for a temporary time delay. This gives you a chance to see exactly 
what is happening in the program. 
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USING PRINT AND STOP 

Insert STOP statements within your program prior to the suspect instruction line. Good 
locations are at the end of specific tasks. Run the program. After the STOP statement 
puts you into direct mode, use the PRINT command to identify clues to the problem by 
determining the values of the various variables, especially those within loops. Check 
these with what you expect. Continue the program with CONT to the next STOP 
statement until you modify your program. 

TRAPPING AN ERROR 

Debugging is the art of detecting the source of problem. The following program is 
perfectly valid; however, it produces an error when B equals zero. 

10 INPUT A,B 
20 PRINT A/B 
30 GOTO 10 
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Although in this case the computer defines the error as a DIVISION BY ZERO 
error, it is not always obvious how the variable B became a zero. It could have been LJ 

derived from a complex formula embedded in your program, or directly inputting the 
value zero into a variable. 

The BASIC TRAP command has a technique of trapping such an error in a _ 

program without crashing. Since you can't always foresee all the possible values of the 
variable B, you can screen the probable error of division of zero by including a TRAP at 
the beginning of the program. 

5 TRAP 50 

10 INPUT A,B I . 

20 PRINTA/B I 

30 GOTOIO "-^ 

50 PRINT"DIVISION BY ZERO IS NOT POSSIBLE" 

60 PRINT"ENTER ANOTHER NUMBER FOR B BESIDES ZERO" 

70 RESUME 



u 



RESUME is required after the TRAP response in order to reactivate the TRAP. If 
you include the option to enter a replacement for B, RESUME without a line number J 

returns to the cause of the error— line 20 — and executes it as follows: 

65 INPUT B 

The use of RESUME NEXT proceeds with the next line after the TRAP command, 
i.e., line 10. 

TRAP tells the computer to go to a specific line number whenever an error occurs. 
Do NOT use TRAP until you have removed all syntax errors first. TRAP can only catch '- 

the error condition it is looking for. An error in the syntax or the logic of your TRAP 
routine may cause an error, or may not catch the error that you are looking for. In other j 

words, TRAP routines are sensitive to errors, too. |_ 
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ERROR FUNCTIONS 

Several reserved variables inherent in the system store information about program 
errors. ER stores the error number. EL stores the relevant program line number. 
ERR$(N) returns the string representing ER or EL. In the example of division by zero, 
ERR$(ER) returns "DIVISION BY ZERO" and ERR$(EL) returns "BREAK". Add 
this to the program in the previous section. See Appendix A for a complete listing of 
errors. 

DOS ERRORS 

Information on disk errors is determined from the variables DS and DS$ where DS is the 
error number (See Appendix B) and DS$ provides the error number, error message, and 
track and sector of the error. DS$ reads the disk error channel and is used during a disk 
operation to determine why the disk drive error light is blinking. 

Trying to read a directory without a disk in place results in the following error 
when the PRINT DS$ command is issued: 

74, DRIVE NOT READY, 00, 00 

Appendix B highlights specific causes of errors. To convert a function key to read 
the disk-drive error channel automatically, use: 

KEY 1, "PRINT DS$ + CHR$(13) 

TRACING AN ERROR 

Some programs have many complex loops that are tedious to follow. A methodical 
step-by-step trace is useful. The BASIC TRON and TROFF commands can be used 
within a program as a debugging tool to trace specific routines. 

Some errors can only be found by acting like the computer and methodically 
following each instruction step-by-step, and then doing all the calculations until you 
discover something wrong. Fortunately the Commodore 128 can trace errors for you. 
Enter the direct command TRON prior to running a program. The program displays each 
line number as they occur in brackets, followed by each result. (To slow down the 
display, hold the Commodore ( C« ) key down.) 

Try it with this double loop: 

10 FORA = IT05 

20 FORB = 2T06 

30 C = B*A:K = K + C:PRINTK 

40 NEXTB:NEXTA 

50 PRINTK 

The results will start off like this: 

[10] [20] [30] [30] [30]2 
[40] [30] [30] [30]5 

meaning the first printed result is the number 2 after operations in lines 10, 20, 30 are 
performed. Then lines 40 and 30 result in 5, etc. Notice three activities were performed 
in line 30. The Trace function is turned off with the direct command TROFF. 
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WINDOWING 

The standard screen display size is 40- or 80-columns by 25 lines. It is often convenient ; j 

to have a portion of the screen available for other work. The process of producing and U 

isolating small segments of your screen is called "windowing." 



DEFINING A WINDOW 

There are two ways to create a window — either directly or within a program using the 
WINDOW command. Using the ESCape key followed by a T or B is all that is 
necessary to describe and set a window. 

Here's how to define a window in direct mode: 

1. Move the cursor to the upper-left comer position of the proposed window. 
Press the (ESC) escape key, then press the letter T key. 

2. Move the cursor to the bottom right comer and press the escape key (ESC) 
then press the letter B key. 

Now that your window is in effect, all commands and listings remain in the 
window until you exit by pressing the HOME key twice. This is useful if you have a 
listing on the main screen and wish to keep it while you display something else in a 
window. See Chapter 13, the Commodore 128 Operating System, under the screen 
editor for special ESCape controls within a window. 

Although it is possible to define several windows simultaneously on the screen, only 
one window can be used at a time. The other windows remain on the display, but they are 
inactive. To re-enter a window you have exited, define the top and bottom comers of the 
window with the ESC T and ESC B commands, respectively, as you did originally. 

The second way to define a window is with the BASIC window command. The 
command: 

WINDOW 20,12,39,24,1 

establishes a window with the top-left comer at column 20, row 12, and the bottom- 
right comer at column 39, row 24. The 1 signifies the area to be cleared. Once this 
command is specified, all activities are restricted to this window. 

Use the window command within a program whenever you want to perform an 
activity in an isolated area on the screen. 
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ADVANCED BASIC 
PROGRAMMING TECHNIQUES 
FOR COMMODORE MODEMS 

The following information tells you how to: 

1. Generate Touch Tone™ frequencies 

2. Detect telephone ringing 

3. Program the telephone to be on or off the hook 

4. Detect carrier 

The programming procedures operate in C128 or C64 modes with the Modem/300. 
In C128 mode, select a bank configuration which contains BASIC, I/O, and the Kemal. 

GENERATING TOUCH TONE 
(DTMF) FREQUENCIES 

Each button on the face of a Touch Tone telephone generates a different pair of tones 
(frequencies). You can simulate these tones with your Commodore 128 computer. Each 
button has a row and column value in which you must store the appropriate memory 
location in order to output the correct frequency. Here are the row and column 
frequency values that apply to each button on the face of your Touch Tone telephone: 



TOUCH TONE FREQUENCY TABLE 

COLUMN 1 (1029 HZ) COLUNIN 2 (1336 HZ) COLUMN 3 (1477 HZ) 

Row 1(697 Hz) 1 2 3 

Row 2 (770 Hz) 4 5 6 

Row 3 (852 Hz) 7 8 9 

Row 4 (941 Hz) * # 



To generate these tones in BASIC with your Commodore 128, follow this procedure: 

1 . Initialize the sound (SID) chip with the following BASIC statements: 

SID = 54272 

POKE SID + 24,15:POKESID + 4,16 

POKE SID + 11,16:P0KESID + 5,0:POKE SID + 12,0 

POKE SID + 6,15*16:POKE SID + 13,15*16:POKE SID + 23,0 

2. Next, select one row and one column value for each digit in the telephone 
number. The POKE statement for each row and column are as follows: 
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Column 1: POKE SID, 117:P0KE SID +1,77 ^ 

Column 2: POKE SID,152:POKE SID + 1,85 

Column 3: POKE SID, 161, POKE SID +1,94 ■ 1 

Row 1: POKE SID + 7,168:POKE SID + 8,44 J 

Row 2: POKE SID + 7,85,:POKE SID + 8,49 

Row 3: POKE SID + 7,150:PbKE SID + 8,54 I i 

Row 4: POKE SID + 7,74 :POKE SID + 8,60 \j 

For example, to generate a tone for the number 1, POKE the values for row 

1 , column 1 as follows j i 

POKE SID + 7,168:POKE SID + 8,44:REM ROW 1 U 

POKE SID,117:P0KE SID + 1,77:REM COLUMN 1 

3. Turn on the tones and add a time delay with these statements: | | 

Li 

POKE SID + 4,17:POKE SID + 11,17:REM ENABLE TONES 
FOR I = 1 TO 50:NEXT:REM TIME DELAY 

4. Turn off the tones and add a time delay with the following statements: L 

POKE SID + 4,16:POKESID + 1 1,1 6:REM DISABLE TONES 

FOR I = 1 TO 50:NEXT:REM TIME DELAY I 

5. Now repeat steps 2 through 4 for each digit in the telephone number you are 
dialing. 

6. Finally, disable the sound chip with this statement: 

POKE SID + 24,0 

DETECTING TELEPHONE RINGING 

To detect whether your telephone is ringing using a Commodore 128, use the following 

statement: ^ 

IF (PEEK(56577) AND 8) = THEN PRINT "RINGING" [J 

If bit 3 of location 56577 contains a value other than 0, the phone is not ringing. 

PROGRAMMING THE TELEPHONE 
TO BE ON OR OFF THE HOOK 

To program the phone to be off the hoojc using a Commodore 128, enter the following 1 

statements in a program: ^ 

OH = 56577:HI = 32:LO = 255 - 32 

POKE (OH + 2),(PEEK(0H + 2) OR HI) I 

POKE OH,(PEEK(OH) AND LO) ^ 

To hang up the phone with a Commodore 128, enter this statement in a program: 

POKE OH,(PEEK(OH) OR HI) 



u 



u 



u 

u 



n 



ONE STEP BEYOND SIMPLE BASIC 105 



Here is the procedure to dial and originate a communication link: 

n 1- Set the modem's answer/originate switch to the "O" for originate. 

! I 2. Program the telephone to be OFF the hook. 

3. Wait 2 seconds (FOR I = 1 to 500:NEXT:REM 2-SECOND DELAY) 

n 4. Dial each digit and follow it with a delay (FOR I = 1 TO 50:NEXT) 

i j 5. When a carrier (high pitched tone) is detected, the Modem/300 automatically 

goes on-line with the computer you are connecting with. 

_ 6. Program the phone to hang up when you are finished. 

' ' Here is the procedure to answer a call: 

1. Set the modem's answer/originate switch to "A" for answer. 

2. To manually answer, program the telephone to be OFF the hook. 

3. To automatically answer, detect if the phone is ringing then program the 
phone to be OFF the hook. 

4. The Modem/300 automatically answers the call. 

5. Program the phone to hang up when you are finished. 

DETECTING CARRIER 

Your Commodore Modem/ 1200 and Modem/300 are shipped from the factory with the 
ability to detect a carrier on the Commodore 128. 

That ability is useful in an unattended auto-answer mode. By monitoring the 
carrier detect line, the computer can be programmed to hang up after loss of carrier. 
Since a caller may forget to hang up, your program should monitor the transmit and 
receive data lines. If there is no activity for five minutes or so, the modem itself should 
hang up. 

To detect carrier on the Commodore 128, the following statement can be used in a 
BASIC program: 

OH = 56577: 

IF ((PEEK (OH) AND 16) = 0) THEN PRINT "CARRIER DETECTED" 

If bit 4 of location 56577 contains a value other than 0, then no carrier is detected. 

ROTARY (PULSE) DIALING 

In order to dial a number with a modem, the software in the computer must generate 
pulses at a prescribed rate. In the United States and Canada, the rate is between 8 and 10 
pulses per second with a 58% to 64% break duty cycle. Most people, however, use 10 
pulses per second with a 60% break duty cycle. 

So to make a call, your software must first take the phone "off-hook" (the 
equivalent of you picking up the receiver). Then to dial the first digit, a 3 for instance. 
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the software must put the phone on-hook for 60 milliseconds and off-hook for 40 
milliseconds. Repeat this process three times to dial a 3. 

The same method is used to dial other digits, except 0, which is pulsed ten times. j i 

Pause at least 600 milliseconds between each digit. J 



1 
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To perform any of the escape capabilities within a program, use a line such as: j 

10150 PRINT CHR$(27) + "U" 



IJ 



y 



to create an underline cursor (in 80-column only). For example, to clear from the cursor 
to the end of a window: 

10160 PRINT CHR$(27) + "@" 

(See the Screen Editor section of Chapter 13 for all the escape and control codes 
available on the Commodore 128.) 

RELOCATING BASIC 

To relocate the beginning or ending of BASIC (in CI 28 mode) for additional memory or 
to protect machine-language programs from being overwritten by BASIC text, it is 
necessary to redefine the starting and ending pointers in required memory addresses. 

The Start of BASIC pointer is located at address 45($2D) and 46($2E). The Top 
of BASIC pointer is at addresses 4626($1212) and 4627($1213). The following instruc- 
tion displays the default locations of the beginning and end of BASIC text, respectively 
(when a VIC bit-mapped screen is not allocated): 

PRINT PEEK(45),PEEK(46),PEEK(4626),PEEK(4627) 
1 28 255 

Since the second number in each case is the high byte value, the default start of 
basic is 28*256 plus 1 or 7169 while the top is 255*256 or 65280. I | 

The following command reduces the size of BASIC text (program) area by 4K by ^ 

lowering the top of BASIC to address 61184 (239*256): 

POKE4626,239:POKE4627,0:NEW j | 

To move the beginning of BASIC up in memory by IK, from 7168 to 8192, use 
this command line: -- 

POKE 46,32:POKE45, 1 :NEW U 

This is the case only when a bit-mapped graphics screen is not allocated. Remem- 
ber, the beginning of BASIC starts at 16384($4000) when a bit-mapped screen is j I 
allocated, and other parts of memory are shifted around. U 
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MERGING PROGRAM AND FILES 

Files can be merged (combined) by opening an existing file and locating the pointer to 
the end of the file so subsequent data can be written to the disk file. CI 28 BASIC has 
included the APPEND command to accomplish this: 

APPEND#5, "HLE NAME" 

opens channel 5 to a previously stored file named "FILE NAME." Subsequent write 
(PRINT#5) statements will add further information to the file. APPEND is primarily 
used for data files. 

The command CONCAT allows the concatenation (combine in sequence) of two 
files or programs while maintaining the name of the first. 

C0NCAT"PART2B" TO "PART2" 

creates a new file called Part 2, consisting of the old Part 2, plus the new Part 2b in 
sequence. Concatenated BASIC program files must be renumbered before they can 
work. Other corrections may also be necessary. 

The BASIC routines described in this chapter can greatly enchance the capabilities 
of your programs. So far, BASIC has been discussed in detail. The machine language 
programming introduced in Chapter 5 can extend program capabilities even further. 
And, as shown in Chapter 7, for still greater flexibility and power, you can combine 
BASIC and machine language in your programs. 
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COMMODORE 128 VIDEO FEATURES 



The CI 28 graphics features include: 

■ Specialized graphics and sprite commands 

■ 16 colors 

■ 6 display modes, including: 

Standard character mode 

Multi-color character mode 

Extended background color mode 

Standard bit map mode 

Multi-color bit map mode 

Combined bit map and character modes (split-screen) 

■ 8 programmable, movable graphic objects called SPRITES which make anima- 
tion possible 

■ Custom programmable characters 

■ Vertical and horizontal scrolling 

The Commodore 128 is capable of producing two types of video signals: 40- 
column composite video, and 80-column RGBI video. The composite video signal, 
channeled through a VIC II (Video Interface Controller) chip (8564) — similar to that 
used in the Commodore 64 — ^mixes all of the colors of the spectrum in a single signal to 
the video monitor. The 8563 separates the colors red, green and blue to drive separate 
cathode ray guns within the video monitor for a cleaner, crisper and sharper image than 
composite video. 

The VIC II chip supports all of the Commodore BASIC 7.0 graphics commands, 
SPRITES, sixteen colors, and the graphic display modes mentioned before. The 80- 
column chip, primarily designed for business applications, also supports sixteen colors 
(a few of which are different from those of the VIC chip), standard text mode, and bit 
map mode. Sprites are not available in 80-colunm output. Bit map mode is not 
supported by the Commodore BASIC 7.0 language in 80-column output. The 80-column 
screen can be bit mapped through programming the 8563 video chip with machine 
language programs. See Chapter 10, Programming the 80-Column (8563) Chip, for 
information on bit mapping the 80-column screen. 



u 



1 ( 
In C128 Mode, Commodore BASIC 7.0 offers fourteen high-level graphics commands U 

that make difficult programming jobs easy. You can now draw circles, boxes, lines, 
points and other geometric shapes, with ten high level conunands such as DRAW, BOX : i 

and CIRCLE, and with four sprite commands. (The sprite commands are described in j ( 

Chapter 9.) You no longer have to be a machine language progranmier, or purchase 
additional graphics software packages to display intricate and visually pleasing graphics 
displays — the Commodore 128 BASIC graphics capabilities take care of this for you. Of j 

course, if you are a machine language programmer or a software developer, the L. 

exceptional CI 28 video hardware features offer high price/performance value for any 
microcomputer application. Pi 
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COMMODORE 128 GRAPHICS PROGRAMMING 



This chapter discusses how to use the Commodore 128 graphics features through 
BASIC using the VIC (40-column) screen. Except for the sprite commands, each 
graphic command is listed in alphabetical order. The sprite commands are covered in 
Chapter 9. Following the format of each command are example programs that illustrate 
the features of that command. Wherever possible, machine language routines are 
included to show how the machine language equivalent of a BASIC graphics command 
operates. 

Chapter 8, The Power Behind Commodore 128 Graphics, is a description of the 
inner workings of the Commodore 128 graphics capabilities. It explains how screen, 
color and character memory are used and how these memory components store and 
address data in each display mode. Chapter 9 then explains how to use sprites with the 
new BASIC commands. Chapter 9 also discusses the inner workings of sprites, their 
storage and addressing requirements, color assignments, and describes how to control 
sprites through machine language. 



P TYPES OF SCREEN DISPLAY 



Your CI 28 displays information several different ways on the screen; the parameter 
"source" in the command pertains to three different modes of screen display. 



TEXT DISPLAY 

Text display shows only text or characters, such as letters, numbers, special symbols 
[~i and the graphics characters on the front faces of most CI 28 keys. The CI 28 can display 

) I text in both 40-column and 80-colunm screen formats. Text display includes standard 

character mode, multi-color character mode and extended background color mode. 
f^ The Commodore 128 normally operates in standard character mode. When you 

I I first turn on the Commodore 128, you are automatically in standard character mode. In 

addition, when you write programs, the C128 is in standard character mode. Standard 

character mode displays characters in one of sixteen colors on a background of one of 
i I sixteen colors. 

' i Multi-color character mode gives you more control over color than the standard 

graphics modes. Each screen dot, a pixel, within an 8-by-8 character grid can have one 
f^ of four colors, compared with the standard mode which has only one of two colors. 

I [ Multi-color mode uses two additional background color registers. The three background 

color registers and the character color register together give you a choice of four colors 
^^ for each dot within an 8-by-8 dot character grid. 

; 1 Each pixel in multi-color mode is twice as wide as a pixel in standard character 

' ' mode and standard bit map mode. As a result, multi-color mode has only half the 

horizontal resolution (160 X 200) of the standard graphics modes. However, the 

nf increased control of color more than compensates for the reduced horizontal resolution. 

1 Extended background color mode allows you to control the background color and 

foreground color of each character. Extended background color mode uses all four 
^ background color registers. In extended color mode, however, you can only use the first 

I j sixty-four characters of the screen code character set. The second set of sixty-four 

characters is the same as the first, but they are displayed in the color assigned to 
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background color register two. The same holds true for the third set of sixty-four "-^ 

characters and background color register three, and the fourth set of sixty-four characters 
and background color register four. The character color is controlled by color memory. I 

For example, in extended color mode, you can display a purple character with a yellow L 

background on a black screen. 

Each of the character display modes receives character information from one of ] 

two places in the Commodore 128 memory. Normally, character information is taken ' f 

from character memory stored in a separate chip called ROM (Read Only Memory). 
However, the Commodore 128 gives you the option of designing your own characters 
and replacing the original characters with your own. Your own programmable characters \ 

are stored in RAM. — ' 

BIT MAP DISPLAY / 

Bit map mode allows you to display highly detailed graphics, pictures and intricate m 

drawings. This type of display mode includes standard bit map mode and multi-color bit 
map mode. Bit map modes allow you to control each individual screen dot or pixel - , 

(picture element) which provides for considerable detail in drawing pictures and other i | 

computer art. These graphic displays are only supported in BASIC by the VIC chip. '"' 

The 80-column chip is designed primarily for character display, but you can bit 
map it through your own programs. See Chapter 10, Programming the 80-Column (8563) j I 

Chip, for detailed information. U 

The difference between text and bit map modes lies in the way in which each 
screen addresses and stores information. The text screen can only manipulate entire [ i 

characters, each of which covers an area of 8 by 8 pixels on the screen. The more jj 

powerful bit map mode exercises c()ntrol over each pixel on your screen. 

Standard bit map mode allows you to assign each screen dot one of two colors. Bit r 

mapping is a technique that stores a bit in memory for each dot on the screen. In i j 

standard bit map mode, if the bit in memory is turned off, the corresponding dot on the 
screen becomes the color of the background. If the bit in memory is turned on, the 
corresponding dot on the screen becomes the color of the foreground image. The series \ | 

of 64,000 dots on the screen and 64,000 corresponding bits in memory control the '—' 

image you see on the screen. Most of the finely detailed computer graphics you see in 
demonstrations and video games are bit mapped high-resolution graphics. | 

Multi-color bit map mode is a combination of standard bit map mode and \_ 

multi-color character mode. You can display each screen dot in one of four colors within 
an 8 X 8 character grid. Again, as in multi-color character mode, there is a tradeoff f / 

between the horizontal resolution and color control. I ! 

SPLIT SCREEN DISPLAY , 

The third type of screen display, split screen, is a combination of the first two types. ) ( 

The split-screen display outputs part of the screen as text and part in bit map mode ^ 
(either standard or muhi-color). The CI 28 is capable of this since it depends on two 

parts of its memory to store the two screens: one part for text, and the other for j 

graphics. 1- 
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COMMAND SUMMARY 



Following is a brief explanation of each graphics conunand available in BASIC 7.0: 



f~^ BOX: Draws rectangles on the bit-map screen 

1 i CHAR: Displays characters on the bit-map screen 

CIRCLE: Draws circles, ellipses and other geometric shapes 
^^ COLOR: Selects colors for screen border, foreground, background and characters 

I I DRAW: Displays lines and points on the bit-map screen 

' ' GRAPHIC: Selects a screen display (text, bit map or split-screen bit map) 

GSHAPE: Gets data from a string variable and places it at a specified position on the 
n bit-map screen 

I I LOCATE: Positions the bit-map pixel cursor on the screen 

PAINT: Fills area on the bit-map screen with color 
p SCALE: Sets the relative size of the images on the bit-map screen 

. I SSHAPE: Stores the image of a portion of the bit-map screen into a text-string variable 

WIDTH: Sets the width of lines drawn 

n The following paragraphs give the format and examples for each of the non-sprite 

' i BASIC 7.0 graphic commands. For a fiiU explanation of each of these commands, see 

the BASIC 7.0 Encyclopedia in Chapter 2. 



BOX 

Draw a box at a specified position on the screen. 

BOX [color source], XI, Yl[,X2,Y2][,angle][,paint] 

where: 



color source 


= Background color 




1 = Foreground color 




2 = Multi-color 1 




3 = Multi-color 2 


XI, Yl 


Top left comer coordinate (scaled) 


X2, Y2 


Bottom right comer opposite XI, YI, is the pixel cursor 




location (scaled) 


angle 


Rotation in clockwise degrees; default is degrees 


paint 


Faint shape with color 




= Do not paint 




1 = Paint 
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EXAMPLES: 

10 COLOR O.ltCOLOR 1,6:C0L0R 4,1 1 

20 GRAPHIC 1,1: REM SELECT BMM CJ 

30 BOX 1,10,10,70,70,90,1:REM DRAW FILLED GREEN BOX 

40 FOR 1=20 TO 140 STEP 3 

50 BOX 1,I,I,I + 60,I+60,I+80:REM DRAW AND ROTATE BOXES , "l 

60 NEXT i 

70 BOX 1,140, 140, 200, 200, 220, 1:REM DRAW 2ND FILLED GREEN BOX [J, 

80 COLOR 1,3: REM SWITCH TO RED 

90 BOX 1,150,20,210,80,90,1:REM DRAW FILLED RED BOX 

100 FOR 1=20 TO 140 STEP 3 

110 BOX 1,1+130, I, 1+190, 1+60, I+70:REM DRAW AND ROTATE RED BOXES 1 

120 NEXT I 

130 BOX 1,270, 140, 330, 200, 210, 1:REM DRAW 2ND FILLED RED BOX 

140 SLEEP 5 :REM DELAY 

150 GRAPHIC 0,1: REM SWITCH TO TEXT MODE 

I 
i 

10 COLOR 0,1:COLOR 4,1:C0L0R 1,6 

20 GRAPHIC 1,1 

30 BOX 1,0,0,319,199 

40 FOR X=10 TO 160 STEP 10 

50 C=X/10 

60 COLOR 1,C 

70 BOX 1,X,X,320-X,320-X 

80 NEXT 

90 SLEEP 5 

100 GRAPHIC 0,1 



y 



10 COLOR 0,1:COLOR 4,1:C0L0R 1,6 

20 GRAPHIC 1,1 

30 BOX 1,50,50,150,120 

40 BOX 1,70,70,170,140 

50 DRAW 1,50,50 TO 70,70 ^ . 

60 DRAW 1,150,120 TO 170,140 

70 DRAW 1,50,120 TO 70,140 * 

80 DRAW 1,150,50 TO 170,70 '—^ 

90 CHAR 1,20, 20, "CUBE EXAMPLE" 

100 SLEEP 5 

110 GRAPHIC 0,1 M 







10 COLOR 1,6:C0L0R 4,1:C0L0R 0,1 

20 GRAPHIC 1,1: REM SELECT BIT MAP MODE 

30 DO :REM CALCULATE RANDOM POINTS 

40 X1=INT(RND(1)*319+1) 

50 X2=INT(RND(1)*319+1) 

60 X3=INT(RND(1)*319+1) 

70 X4=INT(RND(1)*319+1) . , 

80 Y1=INT(RND(1)*199+1) ^ 

90 Y2=INT(RND(1)*199+1) ' ' 

100 Y3=INT(RND(1)*199+1) "^ 

110 Y4=INT(RND(1)*199+1) 

120 BOX 1,X1,Y1,X2,Y2:REM DRAW THE RANDOM BOXES 

130 BOX 1,X3,Y3,X4,Y4 ) ( 

140 DRAW l,Xl,yl TO X3,Y3:REM CONNECT THE POINTS ( ' 

150 DRAW l,X2,y2 TO X4,Y4 '— ^ 

160 DRAW 1,X1,Y2 TO X3,Y4 

170 DRAW 1,X2,Y1 TO X4,Y3 

180 SLEEP2:REM DELAY \ I 

190 SCNCLR 

200 LOOP:REM LOOP CONTINUOUSLY U 
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CHAR 

Display characters at the specified position on the screen. 

CHAR [color source],X,Y[,string][,RVS] 

This is primarily designed to display characters on a bit mapped screen, but it can also 
be used on a text screen. Here's what the parameters mean: 



color source 

X 

Y 

string 

RVS 



= Background 

1 = Foreground 

Character column (0-79) (wraps around to the next line 

in 40-column mode) 

Character row (0-24) 

String to print 

Reverse field flag (O = off, 1 =on) 



EXAMPLE: 



10 COLOR 2,3: REM multi-color 1 = Red 
20 COLOR 3,7: REM multi-color 2 = Blue 
30 GRAPHIC 3,1 
40 CHAR 0,10,10, "TEXT",0 

CIRCLE 

Draw circles, ellipses, arcs, etc. at specified positions on the screen. 

CIRCLE [color source],X,Y[,Xr][,Yr] 
[,sa][,ea][,angle][,inc] 

where: 



color source 



X,Y 

Xr 

Yr 

sa 

ea 

angle 

inc 



= background color 

1 = foreground color 

2 = multi-color 1 

3 = multi-color 2 

Center coordinate of the CIRCLE 

X radius (scaled) 

Y radius (default is xr) 

Starting arc angle (default degrees) 

Ending arc angle (default 360 degrees) 

Rotation in clockwise degrees (default is degrees) 

Degrees between segments (default is 2 degrees) 



EXAMPLES: 



CIRCLEl, 160,100,65,10 
CIRCLEl, 160,100,65,50 
CIRCLEl, 60,40,20, 18„„45 



Draws an ellipse. 
Draws a circle. 
Draws an octagon. 
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CIRCLEl, 260 ,40,20, „„90 Draws a diamond. ^ 

CIRCLEl, 60, 140,20,18,,,, 120 Draws a triangle. 

CIRCLEl, + 2, + 2,50,50 Draws a circle (two pixels down and two to ) I 

the right) relative to the original coordinates of IS 

the pixel cursor. 

j I 
SAMPLE PROGRAMS: [J 

10 REM SUBMARINE TRACKING SYSTEM 

20 COLOR 0,1:COLOR 4,1:C0L0R 1,2:REM SELECT BKGRND, BRDR, SCREEN COLORS 

30 GRAPHIC 1,1:REM ENTER BIT MAP MODE 

40 BOX 1,0,0,319,199 

50 CHAR 1,7, 24, "SUBMARINE TRACKING SYSTEM" :REM DISPLAY CHARS ON BIT MAP 

60 COLOR 1,3: REM SELECT RED 

70 XR=0:YR=0:REM INIT X AND Y RADIUS 

80 DO 

90 CIRCLE 1,160, 100, XR,YR,0, 360, 0,2:REM DRAW CIRCLES 

100 XR=XR+10:YR=YR+10:REM UPDATE RADIUS 

110 LOOP UNTIL XR=90 

120 DO 

130 XR= 0:YR= \ 

140 DO i 

150 CIRCLE 0, 160, 100, XR,YR, 0,360, 0,2 :REM ERASE CIRCLE ^^ 

160 COLOR 1,2 :REM SWITCH TO WHITE 

170 DRAW 1,160,100+XR:DRAW , 160, 100+XR:REM DRAW SUBMARINE BLIP 

180 COLOR 1,3: REM SWITCH BACK TO RED , \ 

190 SOUND 1,16000, 15 :REM BEEP , 

200 CIRCLE 1,160,100,XR,YR,0,360,0,2 :REM DRAW CIRCLE ;J 

210 XR=XR+10:YR=YR+10 :REM UPDATE RADIUS 

220 LOOP UNTIL XR=90 :REM LOOP 

230 LOOP r j 

10 COLOR 0,1:COLOR 4,1:COLOR 1,7 i_J 

20 GRAPHIC 1,1:REM SELECT BMM 

30 X=150:Y= 150:XR=150: YR=150 

40 DO . 

50 CIRCLE 1,X,Y,XR,YR 1 

60 X=X+7 :Y=Y-5:REM INCREMENT X AND Y COORDINATES 

7 XR=XR-5 :YR=YR-5:REM DECREMENT X AND Y RADII 

80 LOOP UNTIL XR=0 

90 GRAPHIC 0,1: REM SELECT TEXT MODE 







y 



COLOR U 

Define colors for each screen area. 

COLOR source number, color number 

This statement assigns a color to one of the seven color areas: 



AREA SOURCE 



II 

40-coluinn (VIC) background '"' 

1 40-column (VIC) foreground 

2 multi-color 1 \ i 

3 multi-color 2 j ' 

4 40-column (VIC) border '-' 

5 character color (40- or 80-column screen) 

6 80-column background color J I 

Colors codes are in the range 1-16. U 
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COLOR CODE 


COLOR 


COLOR CODE 


COLOR 


1 


Black 


9 


Orange 


2 


White 


10 


Brown 


3 


Red 


U 


Light Red 


4 


Cyan 


12 


Dark Gray 


5 


Purple 


13 


Medium Gray 


6 


Green 


14 


Light Green 


7 


Blue 


15 


Light Blue 


8 


Yellow 


16 


Light Gray 



Color Codes in 40-Coiumn (VIC) Output 



EXAMPLE: 

COLOR 0, 1: Changes background color of 40-column screen to black. 
COLOR 5,8: Changes character color to yellow. 

SAMPLE PROGRAM: 



10 REM CHANGE FOREGROUND BIT MAP COLOR 

20 GRAPHIC 1,1 

30 1=1 

40 DO 

50 COLOR 1,1 

60 BOX 1,100,100,219,159 

70 1=1+1 rSLEEP 1 

80 LOOP UNTIL 1=17 

90 GRAPHIC 0,1 

100 REM CHANGE BORDER COLOR 

110 1=1 

120 DO 

130 COLOR 4,1 

140 1=1+1: SLEEP 1 

150 LOOP UNTIL 1=17 

160 REM CHANGE CHARACTER COLOR 

170 1=1 

180 DO 

190 COLOR 5,1 

200 PRINT"COLOR CODE"; I 

210 1=1+1: SLEEP 1 

220 LOOP UNTIL 1=17 

230 REM CHANGE BACKGROUND COLOR 

240 1=1 

250 DO 

260 COLOR 0,1 

270 1=1+1: SLEEP 1 

280 LOOP UNTIL 1=17 

290 COLOR 0,1:COLOR 4,1:COLOR 5,2 



DRAW 

Draw dots, lines and shapes at specified positions on screen. 

DRAW [color source], [XI, Y1][T0 X2, Y2] . . . 

Here are the parameter values: 
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where: 



color source Bit map background 

1 Bit map foreground { j 

2 Multi-color 1 ^ 

3 Multi-color 2 

X1,Y1 Starting coordinate (0,0 through 319,199) (scaled) | j 

X2,Y2 Ending coordinate (0,0 through 319,199) (scaled) |J 



EXAMPLES: 

DRAW 1, 100, 50 Draw a dot. 

DRAW , 10, 10 TO 100,60 Draw a line. 

DRAW , 10, 10 TO 10,60 TO 100,60 TO 10,10 Draw a triangle. 

SAMPLE PROGRAMS: 



\ 



10 COLOR 0,1:COLOR 4,1:C0L0R 1,7 

20 GRAPHIC 1,1:REM SELECT BMM 

30 Y=l 

40 DO 

50 DRAW 1,1, Y TO 320,Y:REM DRAW HORIZONTAL LINES 

60 Y=Y+10 

70 LOOP WHILE Y<200 

75 X=l 

80 DO 

90 DRAW 1,X,1 TO X,200:REM DRAW VERTICAL LINES 

95 X=X+10 

97 LOOP WHILE X<320 

100 COLOR 1,3:REM SWITCH TO RED 

110 DRAW 1,160,0 TO 160,200:REM DRAW X AXIS IN RED 

120 DRAW 1,0,100 TO 320,100:REM DRAW Y AXIS IN RED 

130 COLOR 1,6: REM SWITCH TO GREEN 

140 DRAW 1,0,199 TO 50,100 TO 90,50 TO 110,30 TO 150,20 TO 180,30 

150 DRAW 1,180,30 TO 220,10 TO 260,80 TO 320,0:REM DRAW GROWTH CURVE 

160 CHAR 1,7,23, "PROJECTED SALES THROUGH 1990" 

170 CHAR 1,1, 21, "1970 1975 1980 1985 1990" 

180 SLEEP 10:GRAPHIC 0,1:REM DELAY AND SWITCH TO TEXT MODE 






J 



10 REM DRAW EXAMPLES 

20 COLOR 0,1:COLOR 4,1:C0L0R 1,6 

30 GRAPHIC 1,1 

40 CHAR 1,10,1, "THE DRAW COMMAND" 

50 X=10 ' ( 

60 DO 

70 DRAW 1,X,50:REM DRAW POINTS 

80 X=X+10 

90 LOOP UNTIL X=320 

100 CHAR 1,12,7 , "DRAWS POINTS" \ I 

110 Y=70 \ I 

120 DO "—J 

130 Y=Y+5 

140 DRAW 1,1, Y TO Y,Y :REM DRAW LINES 

150 LOOP UNTIL Y=130 \ j 

160 CHAR 1,18, 11, "LINES" J 

170 DRAW 1,10,140 TO 10,199 TO 90,165 TO 40,160 TO 10,140:REM DRAW SHAPE 1 t_| 

180 DRAW 1,120,145 TO 140,195 TO 195,195 TO 225,145 TO 120,145!REM DRAW SHAPE 

190 DRAW 1,250,199 TO 319,199 TO 319,60 TO 250,199:REM DRAW SHAPE 3 

200 CHAR 1,22, 15, "AND SHAPES" , , 

210 SLEEP 5:GRAPHIC 0,1 J 
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GRAPHIC 

Select a graphic mode. 

1) GRAPHIC mode [,clear][,s] 

2) GRAPHIC CLR 

This statement puts the Commodore 128 in one of the six graphic modes: 



MODE DESCRIPTION 

40-colunin text 

1 standard bit map graphics 

2 standard bit map graphics (split screen) 

3 multi-color bit map graphics 

4 multi-color bit map graphics (split screen) 

5 80-column text 



EXAMPLES: 



GRAPHIC 1,1 
GRAPHIC 4,0,10 

GRAPHIC 
GRAPHIC 5 



Select standard bit map mode and clear the bit map. 
Select split screen multi-color bit map mode, do not clear 
the bit map and start the split screen at line 10. 
Select 40-column text. 
Select 80-column text. 



GRAPHIC CLR Clear and deallocate the bit map screen. 
SAMPLE PROGRAM: 

10 REM GRAPHIC MODES EXAMPLE 

20 COLOR 0,1;COLOR 4,1:C0L0R 1,7 

30 GRAPHIC 1,1: REM ENTER STND BIT MAP 

40 CIRCLE 1,160,100,60,60 

50 CIRCLE 1,160,100,30,30 

60 CHAR 1,9,24, "STANDARD BIT MAP MODE" 

70 SLEEP 4 

80 GRAPHIC 0,1: REM ENTER STND CHAR MODE 

90 COLOR 1,6: REM SWITCH TO GREEN 

100 FOR I=1T0 25 

110 PRINT"STANDARD CHARACTER MODE" 

120 NEXT 

130 SLEEP 4 

140 GRAPHIC 2,1:REM SELECT SPLIT SCREEN 

150 CIRCLE 1,160,70,50,50 

160 CHAR 1,14,1, "SPLIT SCREEN" 

170 CHAR 1,8,16, "STANDARD BIT MAP MODE ON TOP" 

180 FOR 1=1 TO 25 

190 PRINT" STANDARD CHARACTER MODE ON THE BOTTOM" 

200 NEXT 

210 SLEEP 3: REM DELAY 

220 SCNCLR:REM CLEAR SCREEN 

230 GRAPHIC CLR:REM DE-ALLOCATE BIT MAP 

GSHAPE 

Retrieve (load) the data from a string variable and display it on a specified coordinate. 

GSHAPE string variable [X,Y][,mode] 
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where: 

string Contains shape to be drawn 

X,Y Top left coordinate (0,0 through 319,199) telling where to 

draw the shape (scaled — ^the default is the pixel cursor) 
mode Replacement mode: 

= place shape as is (default) 

1 = invert shape 

2 = OR shape with area 

3 = AND shape with area 

4 = X0R shape with area 

SAMPLE PROGRAM: 

10 REM DRAW, SAVE AND GET THE COMMODORE SYMBOL 

20 COLOR 0,1:COLOR 4,1:C0L0R 1,7 

30 GRAPHIC 1,1:REM SELECT BMM 

40 CIRCLE 1,160, 100, 20, 15 :REM OUTER CIRCLE 

50 CIRCLE 1,160, 100, 10, 9:REM INNER CIRCLE 

60 BOX 1,165,85, 185, 115:REM ISOLATE AREA TO BE ERASED 

70 SSHAPE A$,166,85,185,115:REM SAVE THE AREA INTO AS 

80 GSHAPE AS, 166, 8 5, 4: REM EXCLUSIVE OR THE AREA-THIS (ERASES) TURNS OFF PIXELS 

90 DRAW 0,165,94 TO 165,106:REM TURN OFF (DRAW IN BKGRND COLOR) PIXELS IN "C=" 

100 DRAW 1,166,94 TO 166,99 TO 180,99 TO 185,94 TO 166,94:REM UPPER FLAG 

110 DRAW 1,166,106 TO 166,101 TO 180,101 TO 185,106 TO 166,106:REM LOWER FLAG 

120 PAINT 1,160, 110 :REM PAINT "C" 

130 PAINT 1,168,98 :REM UPPER FLAG 

140 SLEEP 5: REM DELAY 

150 SSHAPE BS,137,84,187,116:REM SAVE SHAPE INTO BS 

160 DO 

170 SCNCLR 

180 Y=10 

190 DO 

200 X=10 

210 DO 

220 GSHAPE B5,X,Y:REM GET AND DISPLAY SHAPE 

230 X=X+50:REM UPDATE X 

240 LOOP WHILE X<280 

250 Y=Y+40:REM UPDATE Y 

260 LOOP WHILE Y<160 

270 SLEEP 3 

280 LOOP 

LOCATE 

Position the bit map pixel cursor (PC) on the screen. 

LOCATE X, Y 



EXAMPLE: 

LOCATE 160,100 

LOCATE +20,100 
LOCATE + 30, + 20 

PAINT 

Fill area with color. 



Position the PC in the center of the bit map screen. 

Nothing will be seen until something is drawn. 

Move the PC 20 pixels to the right of the last PC position 

and place it at Y coordinate 100. 

Move the PC 30 pixels to the right and 20 down from 

the previous PC position. 
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PAINT [color source], X,Y[,mode] 



n 

n 
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where: 

color source 



~ X,Y 

i \ mode 


I \ EXAMPLE; 



Bit map background 

1 Bit map foreground (default) 

2 Multi-color 1 

3 Multi-color 2 

starting coordinate, scaled (default at pixel cursor (PC)) 

= paint an area defined by the color source selected 

1 = paint an area defined by any non-background source 



10 CIRCLE 1, 160,100,65,50 
20 PAINT 1, 160,100 



10 BOX 1, 10, 10,20,20 
20 PAINT 1, 15, 15 



30 PAINT 1, -hlO, -1-10 



SCALE 

Alter scaling in graphics mode. 

SCALE n [,Xmax,Ymax] 

where: 

n = 1 (on) or (off) 
X max = 320-32767 

(default = 1023) 
Y max = 200-32767 

(default = 1023) 

The default scale values are: 



Multi-color mode 
Bit map mode 



Draws an outline of a circle. 

Fills in the circle with color from source 1 (ViC 

foreground), assuming point 160,100 is colored 

in the background color (source 0). 

Draws an outline of a box. 

Fills the box with color from source 1 , assuming 

point 15,15 is colored in the background source 

(0). 

PAINT the screen in the foreground color source 

at the coordinate relative to the pixel cursor's 

previous position plus 10 in both the vertical and 

horizontal positions. 



X = to 159 Y = to 199 
X = to 319 Y = to 199 



EXAMPLES: 



10 GRAPHIC 1,1 

20 SCALE LCIRCLE 1,180,100,100,100 



Enter standard bit map, turn scaling 
on to default size (1023, 1023) and 
draw a circle. 
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10 GRAPHIC 1 ,3 Enter multi-color mode, turn scaling 

20 SCALE 1,1000,5000 on to size (1000,5000) and draw a 



EXAMPLES: 



SSHAPE A$,10,10 Saves a rectangular area from the coordinate 10,10 

to the location of the pixel cursor, into string vari- 
able A$. 

SSHAPE B$, 20,30,47,51 Saves a rectangular area from top left coordinate 



y 



30 CIRCLE 1,180,100,100,100 circle. )/ 



( 



SSHAPE 

Save shapes to string variables. i i 

SSHAPE and GSHAPE are used to save and load rectangular areas of multi-color or bit tJ 

mapped screens to/from BASIC string variables. The command to save an area of the 

screen into a string variable is: I ' 

SSHAPE string variable, XI, Yl [,X2,Y2] ^ 

where: .- , 

string variable String name to save data in Lj 

X1,Y1 Comer coordinate (0,0 through 319,199) (scaled) 

X2,Y2 Comer coordinate opposite (X1,Y1) (default is the PC) 



\ I 
\ I 
U 



(20,30) through bottom right coordinate (47,51) into \ I 
string variable B$. 
SSHAPE D$, -I- 10, -I- 10 Saves a rectangular area 10 pixels to the right and 10 

pixels down from the current position of the pixel ) j 

cursor. LJ 

Also, see the example program under GSHAPE for another example. ^ i 

\ I 

WIDTH "^ 

Set the width of drawn lines. ^^ , 

WroTH n U 



This command sets the width of lines drawn using BASIC'S graphic commands to either 

single or double width. Giving n a value of 1 defines a single width line; a value of 2 | j 

defines a double width line. I— ' 

EXAMPLES: \ j 

WIDTH 1 Set Single width for graphic commands 
WIDTH 2 Set double width for drawn lines 



n 
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WHAT IS MACHINE LANGUAGE? 



WHY USE MACHINE LANGUAGE? 



u 



This chapter introduces you to 6502-based machine language programming. Read this 
section if you are a beginner or novice machine language programmer. This section 
explains the elementary principles behind programming your Commodore 128 in machine 
language. It also introduces you to the 8502 machine language instruction set and how 
to use each instruction. If you are already an experienced machine language program- 
mer, skip this section and continue to the 8502 Instruction and Addressing Table at the i i 
end of the chapter for reference material on machine language instructions. The 8502 jj 
instruction set is exactly the same as the 6502 microprocessor instruction set. 



Li 



LJ 



Every computer has its own machine language. The type of machine language depends |_j 

on which processor is built into the computer. Your Commodore 128 understands 8502 
machine language, which is based on 6502 machine language, to carry out its opera- , 

tions. Think of the microprocessor as the brain of the computer and the instructions as ) 

the thoughts of the brain. ^ 

Machine language is the most elementary level of code that the computer actually 
interprets. True machine language is composed of binary strings of zeroes and ones. \ ! 

These zeroes and ones act as switches to the hardware, and tell the circuit where to apply {J 

voltage levels. 

The machine language discussed in this chapter is symbolic 6502 Assembly ^ 

language as it appears in the CI 28 Machine Language Monitor. This is not the 
full-blown symbolic assembly language as it appears in an Assembler package, since 
symbolic addresses or other higher level utilities that an Assembler software package 
would provide are not implemented. 

Machine language is the lowest level language in which you can instruct your 
computer. BASIC is considered a high-level language. Although your Commodore 128 
has BASIC built in, the computer must first interpret and translate it to a lower level that 
it can understand, before the computer can act upon BASIC instructions. \ \ 

With each microinstruction, you give the computer a specific detail to perform. '— ' 

The computer takes nothing for granted in machine language, unlike BASIC, where 
many unnoticed machine-level functions are performed by one statement. One BASIC \ I 

statement requires several machine language instructions to perform the same operation. jj 

Actually, when you issue a BASIC conmiand, you are really calling a machine language 
subroutine that performs a computer operation. 
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If machine language is more intricate and complicated than BASIC, why use it? Certain 
applications, such as graphics and telecommunications, require machine language be- 
cause of its speed. Since the computer does not have to translate from a higher-level 1 ! 
language, it runs many times faster than BASIC. L-l 
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Programs such as those used in arcade games cannot operate in the relatively slow 
speed of BASIC, so they are written in machine language. Other instances dictate the 
use of machine language simply because those programming operations are handled 

I i better than in a high-level language like BASIC. But some programming functions such 

as string operations are easier in BASIC than in machine language. In these cases, 
BASIC and machine language can be used together. You can find information on how to 
mix machine language with BASIC in Chapter 7. 

Inside your computer is a perpetually running program called the operating 
system. The operating system program controls every function of your computer. It 

I I performs functions at lightning speeds you are not even aware of. 

' ' The operating system program is written entirely in machine language and is 

stored in a portion of the computer called the Kemal ROM. (Chapter 13 describes how 

n to take advantage of the machine language programs within the Kemal, and how to use 

/ I parts of the operating system in your own machine-language programs.) 

Though machine language programming may seem more complicated and difficult 
than BASIC at first, think back to when you didn't know BASIC or your first 
programming language. That seemed difficult at first, too. If you learned BASIC or 
another programming language, you can learn machine language. Although it's a good 
idea to learn a higher-level language such as BASIC before you start machine language, 
it's not absolutely necessary. 



WHAT DOES MACHINE LANGUAGE 
LOOK LIKE? 



Chapter 2 describes the C128 BASIC 7.0 language. Most statements in BASIC start 
with a BASIC verb or keyword, followed by an operand. The BASIC keywords 
resemble English verbs. The operands are variables, or constants, that are part of an 
expression. For example, A -I- B = 2, is an expression where A, B, and 2 are operands 
in the expression. Machine-language instructions are similar, though they have a uniform 
format. Here's the format for an 8502 symbolic machine language instruction as it 
appears in the CI 28 Machine Language Monitor: 

OP-CODE FIELD OPERAND FIELD 

OPERATION CODE (OP-CODE) FIELD 

The first part of a machine-language instruction is called the operation code or op-code. 
The op-code is comparable to a BASIC verb, in that it is the part of the instruction that 
performs an action. A machine language op-code is also referred to in an assembly 
language as a mnemonic. All 8502 (6502) machine language assembler mnemonics are 
three-letter abbreviations for the functions they perform. For example, the first and most 
common instruction you will learn is LDA, which stands for LoaD the Accumulator. 
This chapter defines all of the mnemonics. 
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OPERAND FIELD 
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The second portion of a machine-language instruction is the OPERAND field. In the j I 

CI 28 Machine Language Monitor, the operand is separated from the op-code with at o 

least one space and preceded by a ($) dollar sign, ( + ) plus sign (decimal), (&) 
ampersand (octal), or a (%) percent (binary) sign to signify that the operand is a ^ i 

hexadecimal, decimal, octal or binary number. An ADDRESS is the name of or jj 

reference to a specific memory location within the computer. 

The number of a memory location is its address, just like houses on your street are 
numbered. Addresses in your computer are necessary so they can receive, store and send 
(LOAD) data back and forth to the microprocessor. i— ' 

When you use the Commodore 128's built-in machine-language monitor, all 
numbers and addresses default to hexadecimal numbers, but they can be represented in j i 

decimal, octal or binary. The address is the hexadecimal number of the specified [j 

memory location. When you use an ASSEMBLER, the addresses are referred to as 
symbolic addresses. Symbolic addresses allow you to use variable names, instead of . , 

absolute addresses that specify the actual memory location. You declare the symbolic j I 

address to be the numeric address in the beginning of your machine language program or 
allow the assembler to assign the address. 

When you refer to that address later in the program, you can refer to the symbolic 
address rather than to the absolute address as does the Machine Language Monitor. 
Using an assembler and symbolic addresses make programming in machine language 
easier than using the machine-language monitor and absolute addresses. You will 
learn about the eleven addressing modes later in this chapter. 

As you know, the second part of a machine-language instruction is the OPER- 
AND. A machine language operand can be a constant; it does not necessarily have to be 
an address reference. When a constant in machine language appears in place of an 
address as the second part of an instruction, an operation is performed on a data value 
rather than a memory location. 

A pound sign (#) in front of the operand signifies inmiediate addressing, which 
you will learn more about later in the chapter. The pound sign is only used as an aid for 
the symbolic language programmer. The pound sign tells the computer to perform 
machine-language instruction on a constant, and not an address. In the case of the 
Machine Language Monitor, variable names are not allowed. To represent variables in 
the monitor, you must reference a memory location where your variable data value is 
stored. 

EXAMPLES OF U 

MACHINE-LANGUAGE INSTRUCTIONS 

LDA $100 ; Absolute addressing [J 

LDA $10 ; Zero page absolute addressing 

LDA ($FA),Y ; Indirect indexed addressing 

LDA $2000,X ; Indexed addressing (absolute) j j 

LDA #$10 ; Immediate addressing (constants) U 
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THE SIMILARITIES AND DIFFERENCES BETWEEN AN 
p ASSEMBLER AND A MACHINE LANGUAGE MONITOR 

An assembler and machine-language monitor both provide for symbolic op-codes. 
Assemblers typically allow symbolic operands as well, whereas the CI 28 machine- 
language monitor refers to addresses and operands literally (absolutely). 

An assembler typically has two forms of a file: source code and object code. 
Source code is the file you create when you are writing the program including symbolic 
start addresses and comments. 

The source code file is not executable. It must be assembled (in an intermediate 
process) into object code, which is executable code. 

The machine language monitor start address is determined by where you place the 
actual instructions in memory. The monitor does not provide for comments. The resulting 
program, once it is input, is executed immediately as a binary file. No intermediate 
assembly step is needed. 
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THE 8502 MICROPROCESSOR REGISTERS 

You have learned that an address is a reference to a specific memory location among the 
2 banks of RAM within the Commodore 128. Separate and independent of those RAM 
locations are special purpose work and storage areas within the microprocessor chip 
itself, called registers. These registers are where the values are manipulated. The 
manipulation of the microprocessor registers and their communication with the comput- 
er's memory (RAM and ROM) accomplishes all the functions of machine language and 
your computer's operating system. 

Figure 5-1 shows a block diagram of the 8502 microprocessor. As shown in the 
figure, the 8502 microprocessor registers are: 

Accumulator 
X index register 
Y index register 
Status register 
Program counter 
Stack pointer 

Following are descriptions of these registers. 

THE ACCUMULATOR 

The accumulator is one of the most important registers within the 8502 microprocessor. 
As the name implies, it accumulates the results of specific operations. Think of 
the accumulator as the doorway to your microprocessor. All information that enters 
your computer must first pass through the accumulator (or the X or Y register). 



128 COMMODORE 128 



For example, if you want to store a value within one of the RAM locations, you must 
first load the value into the accumulator (or the X or Y register) and then store it into the 
specified RAM location. You cannot store a value directly into RAM, without placing it 
into the accumulator or the index registers first. (The index registers are described in the 
following section.) 
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Figure 5-1. 8502 Block Diagram 
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All mathematical operations are performed within the arithmetic logic unit (ALU) 
and stored in the accumulator. It is considered a temporary mathematical work area. For 
example, you want to add two numbers, 2 + 3. Fu-st, load the accumulator with the 2. 
Next add 3 with the ADC mnemonic. Now, you want to perform another operation. You 
must store the answer from the accumulator into a RAM location before you perform the 
next math operation. If you don't, your original answer is erased. 

The accumulator is so important that it has an addressing mode of its own. All the 
instructions using this mode pertain specifically to the accumulator. The following three 
sample instructions pertain solely to the accumulator in its own addressing mode: 

LDA - LOAD accumulator with memory 

STA - STORE the accumulator in memory 

ADC - ADD contents of memory to the accumulator 

Details on all of the accumulator addressing commands are given later in this chapter. 

THE X AND Y INDEX REGISTERS 

The second most used registers are the X and Y index registers. These index registers are 
used primarily to modify an address by adding an index within a machine-language 
instruction. They also can be used as temporary storage locations or to load values and 
store them in RAM like the accumulator. 

When modifying an address, the contents of the index registers are added to an 
original address, called the base address, to find an address relative to the base address. 
The resulting address yields the effective address — ^i.e., the location where a data value 
is stored or retrieved. The effective address is acted upon by machine-language instruc- 
tions. For example, you want to place the value in locations 1024 through 1034. In 
BASIC, here's how you do it: 

10 FOR I = 1024 to 1034 
20 POKE 1,0 
30 NEXT 

Here's how you do it in symbolic machine language by using the X or Y index 
register. NOTE: Don't worry if you don't understand all of the following instructions. They 
are discussed fully in the TYPES OF INSTRUCTIONS section, later in this chapter. 

LDA #$00 Load the Accumulator with 

TAX Transfer the contents of Accumulator (0) to X 
Register. 

START STA $0400,X Store contents of Accumulator in address $0400 + X 

INX Increment the X register 

CPX #$0B Compare the X register with $0B (1 1 decimal) 

BNE START If X register does not equal 1 1 branch to START. 

BRK Stop 

* = In the machine-language monitor the symbolic label START is not allowed, so it 
would appear as an absolute address reference (eg; $183B). 
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The BASIC example above places a in locations (addresses) 1024 through 1034. 
Line 10 sets up a loop from memory locations 1024 to 1034. Line 20 POKEs the value 
into the location specified by I. The first time through the loop, I equals 1024. The 
second time through the loop, I equals 1025 and so on. Line 30 increments the index 
variable I by 1 each time it is encountered. 

The previous machine-language example accomplishes the same task as the BA- 
SIC example. LDA #$00 loads a into the accumulator. TAX transfers the contents of 
the accumulator into the X-index register. The following machine-language instructions 
form a loop: 

START STA $0400,X 
INX 

CPX #$0B 
BNE START 

Here's what happens within the loop. STA $0400,X stores a in location $0400 
(hex) the first time through the loop. Location $0400 is location 1024 decimal. INX 
increments the X register by 1, each cycle through the loop. CPX #$0B compares the 
contents of the X register with the constant 1 1 ($0B). If the contents of the X register do 
not equal 11, the program branches back to START STA $0400,X and the loop is 
repeated. 

The second time through the loop, is stored in address $0401 (1025 decimal) and 
the X register is incremented again. The program continues to branch until the contents 
of the X register equal 1 1 . 

The effective address for the first cycle through the loop is $0400 which is 1024 
decimal. For the second cycle through the loop the effective address is $0400 -I- 1 , and 
so on. Now you can see how the index registers modify the address within machine- 
language instruction. 

THE STATUS REGISTER 

The microprocessor's status register indicates the status of certain conditions within the 
8502. The status register is controlled by seven programming states of the microproces- 
sor, and indicates the conditions with flags. The status register is one byte, so each flag 
is represented by a single bit. Bit 5 is not implemented. 

Branching instructions check (4 of the 7 bits in) the status register to determine 
whether a condition has occurred. The conditions for branching pertain to the value of 
the bits in the status register. If a condition is true, meaning the FLAG bit corresponding 
to one of the four conditions is high (equal to a 1), the computer branches. If the 
condition you are testing is not true, the computer does not branch and the program 
resumes with the instruction immediately following the branch. 

Figure 5-2 shows the layout of the 8502 status register and lists the conditions 
the status register flags. 
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PROCESSOR STATUS REG "P" 



.CARRY 1 s TRUE 
.ZERO 1 s RESULT ZERO 

.IRQ DISABLE 1 s DISABLE 

■ DEQMAL MODE 1 = TfHiE 
' BRK COMMAND 



-►OVERFLOW 
-► NEGATIVE 



1 s TRUE 
1 * NEQ 



Figure 5-2. 8502 Status Register 



The Carry bit (0) is set if an addition operation carries a bit into the next position 
to the left of the leftmost bit. The Carry bit is set by other conditions, of which this is 
one. The SEC instruction sets the Carry bit. CLear the Carry bit with the CLC 
instruction. 

The Zero bit (1) is set if the result of an operation equals zero. The command BEQ 
stands for Branch on result EQual to Zero. The command BNE stands for Branch on 
Result Not Equal to zero. If the zero bit in the status register is set, the program 
branches to the address relative to the current program counter value (for a BEQ 
instruction). Otherwise, the BEQ command is skipped and the program resumes with the 
instruction immediately following the BEQ statement. 

The IRQ Disabled bit (2) is set if your program requests interrupts to be dis- 
abled with the SEI command (Set Interrupt Disable Status). The Disable Interrupt 
Status bit is cleared with the CLI command (CLear Interrupt Disable bit) to permit 
interrupts to occur. You will learn more about programming interrupts in the section 
entitled TYPES OF INSTRUCTIONS and in the Raster Interrupt program explanation in 
Chapter 8. 

The microprocessor sets the Decimal Mode bit (3) if you instruct the microproces- 
sor to SEt Decimal Mode with the SED instruction. CLear the Decimal Mode bit with 
the CLD instruction, CLear Decimal Mode. 

The BRK flag (bit 4) operates similar to the IRQ disable flag. If a BRK instruction 
occurs, it is set to 1. Like an IRQ interrupt, the BRK causes the contents of the 
program counter to be pushed onto the stack. The contents of the status register is 
pushed on top of the stack and evaluated. If the BRK flag is set, the operating system 
or your application program must evaluate whether or not a BRK or interrupt has 
occurred. 

If the BRK flag is cleared once the status register is pushed onto the stack, the 
processor handles this as an interrupt and services it. Unlike an interrupt, the BRK flag 
causes the address of the program counter plus two to be saved. The microprocessor 
expects this to be the address of the next instruction to be executed. You may have to 
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adjust this address since it may not be the actual address of the next instruction within 
your program. 

The Overflow flag (bit 6) is set by a signed operation overflowing into the sign 
bit (bit 7) of the status register. You can clear the Overflow bit in the status register with 
the CLV instruction (CLear Overflow flag). You can conditionally branch if the 
Overflow bit is set with the BVS (Branch Overflow Set) instruction. Similarly, you can i 

conditionally branch if the overflow bit is clear with the BVC (Branch Overflow Clear) I 

instruction. The BIT instruction can be used to intentionally set the overflow flag. 

The microprocessor sets the negative flag (bit 7) if the result of an arithmetic 
operation is less than 0. You can conditionally branch if the result of an arithmetic 
operation is negative, using the BMI instruction, (Branch on result Minus) or positive 
using the BPL instruction, (Branch on Result Positive). 

The status register indicates seven important conditions within the microprocessor 
while your machine language program is executing. Your program can test for certain 
conditions, and act upon the results. It gives you a way to conditionally control certain 
machine level functions depending on the value of the status flags. 

THE PROGRAM COUNTER 

So far all of the registers within the 8502 are 8 bits, or one byte. The program counter 
is twice as wide (16 bits) as the accumulator, X or Y registers or the status register. The 
program counter is a 16-bit register because it holds the current address of the next 
instruction to be executed. The addresses used in an 8502-based microprocessor are all 16 
bits wide. They have to be in order to address all locations within each 64K RAM 
bank. 

The program counter holds the address of the next instruction to be executed. It 
fetches the addresses of the instructions sequentially (usually) and places them on the 
16-bit address bus. The processor obtains the data or instructions at the specified 16-bit 
address from the data bus. Then they are decoded and executed. 
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THE STACK POINTER 

Within the RAM of the Commodore 128 is a temporary work area called the stack. It 
starts at location decimal 256 and ends at location 511 (hex $100 to $1IT). This area of 
computer RAM is referred to as page 1. Paging is explained in the next section. 

The stack is used for three purposes in your computer: temporary storage, control 
of subroutines, and interrupts. The stack is a LIFO (Last In, First Out) structure which 
means the last value placed on the stack is the first one taken off. When you place a , 

value on the stack, it is referred to as pushing. When you take a value off the stack, it is J 

considered pulling or popping. 

Think of the structure as a stack of lunch trays in a cafeteria. The first tray used is 
the one that is pulled off the top. The last one used is the one on the bottom, and it is 
used only if all the others are pulled off before it. 

The stack pointer is the address of the top stack value (plus 1). When a value 
is pulled from the stack, the stack pointer then indicates the new address of the 
next item on the stack. When a subroutine is called or an interrupt occurs, the L_ 
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address where the interrupt or subroutine occurs is pushed on top of the stack. Once 
the interrupt or subroutine is serviced, the address where it occurred is popped off 
the stack and the computer continues where it left off when the interrupt or subroutine 
occurred. 



16-BIT ADDRESSING: 

THE CONCEPT OF PAGING 

The Commodore 128 contains 128K of Random Access Memory (RAM). This means 
you have two banks of 65536 (64K) RAM memory locations (minus two for locations 
and 1, which are always present in a RAM bank). Since the 8502 is an 8-bit micropro- 
cessor, it needs two 8-bit bytes to represent any number between and 65535. One 
eight-bit byte can only represent numbers between and 255. Your computer needs a 
way to represent numbers as large as 65535 in order to address all the memory 
locations. 

Here's how your computer represents the largest number in one 8-bit byte. The 
computer stores it as a binary number. You usually represent it as a hexadecimal number 
in your machine-language programs. Figure 5-3 shows the relationship between binary, 
hexadecimal and decimal numbers. 



BINARY HEXADECIMAL DECIMAL 

1 eight-bit Byte = 11111111 $FF 255 

Figure 5-3. Comparison of Number Systems 



A byte contains eight binary digits (bits). Each bit can have a value of or 1. The 
largest number your computer can represent in eight binary digits is 1 1 1 1 1 I 1 1, 
which equals 255 in decimal. This means all eight bits are set, or equal to 1. A 
bit is considered off if it is equal to 0. In converting binary to decimal, all the binary 
digits that are set are equal to 2 raised to the power of the bit position. The bit 
positions are labeled through 7 from right to left. Figure 5-4 provides a visual 
representation of converting binary to decimal. 



2? 2* 2* 2'* 2^ 2^ 2' 
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One binary byte =11111111 

The byte in decimal = 128 + 64 + 32 + 16 + 8 + 4 + 2 + 1 =255 

Figure S-4. Binary/Decimal Conversion 
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The top of each column represents the value of 2 raised to the power of the bit 
position. Since each bit is turned on when you represent the largest number in one byte, 
add all the values at the bottom of each to obtain the decimal equivalent. Figure 5-5 
shows another example that converts the binary number 1 1 1 1 to decimal. 



Figure 5-5. Binary/Decimal Conversion 



Higli Byte 


2is 2" 2" 2" 2" 2"* 2* 2* 


One binary byte = 


11111111 


The byte in 
decimal = 


32768 + 16384+ 8192 + 4096 + 2048 + 1024 + 512 +256 = 65280 


Low Byte 


27 2* 2* 1* 2' 2* 2> 2" 


One binary byte = 


11111111 


The byte in 
decimal 


128+64 + 32 + 16+8 + 4 + 2 + 1= 255-255 

65535 
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2' 2* 2* 2" 2' 2^ 2' 2" j 

One binary byte =11001010 
The byte in decimal = 128 +64+0 + + 8 + + 2 + 0= 202 
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Remember, only add the values of two raised to the bit position if the bit is set. U 

If a bit is off, it equals zero. 

Now that you can convert one byte from binary to decimal, you are probably 
wondering what this has to do with 16-bit addressing. We mentioned before that the J 

program counter— the register responsible for storing the address of the next instruction 
to be executed — is 16 bits wide. This means it uses two bytes side-by-side to calculate 
the address. 

You just learned about the low byte, the lower half of the 16 bits used to represent 
an address. The upper half of the 16-bit address is called the high byte. The high byte 
calculates the upper half of the address the same way as the low byte, except the bit 
position numbers are labeled from 8 on the right to 15 on the left. When you raise 2 to 
the power of these bit positions, and add the resulting values to the low byte of the 
address, you arrive at addresses that go up to 65535. This allows your computer 
to represent any number between and 65535, and address any memory location 
within each 64K RAM bank. Figure 5-6 is an illustration of a 16-bit address in 
decimal: 



u 
u 
u 

I 

j 



Figure 5-6. Example of 16-Bit Address in Decimal 
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You can see that the highest number of the high byte of the 16-bit address is 
65280. And you know that the highest number of the low byte of the 16-bit address 
equals 255. Add the highest high-byte and the highest low-byte number (65280 + 255), 
to arrive at 65535, the highest address within each of the two 64K RAM banks. 

When the microprocessor calculates the address of the next instruction, it looks at 
the high byte of the 16-bit program counter. Try to think of the high byte of the address 
as just another 8-bit byte. If this was the case, the bit positions would be labeled from 
on the right through 7 on the left, just like the low byte of the address. Therefore, the 
largest number this 8-bit byte can represent again is 255 decimal. 

The value in the high byte determines which 256-byte block is accessed. These 
256-byte blocks are referred to as pages. The high byte determines the page boundary of 
the address, so the high byte is calculated in increments of 256 bytes. The high byte of 
the program counter determines which of the possible 256 pages is being addressed. If 
you multiply the number of possible pages, 255 by 256 bytes, you realize the highest 
page starts at location 65280, decimal, the same number as in the high byte in Figure 
5-6. Location 65280 is the highest page boundary addressable. 

What if you want to address a memory location that does not lie on a page 
boundary? That's where the low byte of the 16-bit address comes in. 

The high byte of the program counter represents the 256-byte page boundary. 
All addresses between boundaries are represented by the low byte. For example, to 
address location 65380 decimal represent the high byte as 255, since 255 times 
256 equals 65280. You still have to move 100 addresses higher in memory to location 
65380. 

The low byte contains the value 100 decimal. The low byte value is added to the 
high byte to find the actual, or effective address. 

When you look at the memory map of your Commodore 128, you will see 
references to the low byte and high byte pointers or vectors to certain machine-language 
routines within the operating system or to important system memory locations, like the 
start of BASIC. 

You can find out the contents of these addresses and where the routines reside in 
your Commodore 128's memory by using the PEEK command in BASIC, or the 
Memory command in the Machine Language Monitor. To find the effective address 
using BASIC, look in the memory map for the reference to a specific routine or system 
function, sometimes called a vector. PEEK the high byte, the page number of the 
routine. Multiply by 256 to find the page boundary. Then PEEK the low byte and add it 
to the page boundary to arrive at the effective decimal address. 

Keep in mind that all the address calculations are performed in binary. They are 
explained in decimal so they're easier to understand. In your machine language pro- 
grams, you will usually reference memory in hexadecimal notation, explained in the 
next section. 
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HEXADECIMAL NOTATION 



3A (hexadecimal), or as 00111010 (binary)? 

Once values are translated from the higher level language into a form that the 
microprocessor can understand (binary digits or bits), they are interpreted as electronic 
switches by the internal circuitry. The switches determine if an electronic impulse will 
be transmitted by the integrated circuit (I.C.) to perform a specific function, such as 
addressing a memory location. If the bit equals 1, the switch is interpreted as on, which 
sends a voltage level (approximately 3 to 5 volts) through the I.C. If the binary digit is 
equal to 0, no voltage is transmitted. Though this is a simplified illustration, you get an 
idea of how the microcomputer system can translate, process and perform the instruc- 
tions you give to your computer. The hardware and software merge here, at machine 
level. 

UNDERSTANDING HEXADECIMAL 
(HEX) NOTATION 

The key behind understanding hexadecimal (base 16) numbers is to forget about decimal 
(base 10). Hexadecimal digits are labeled from through 9 and continuing with A 
through F, where F equals 15 in decimal. By convention, hexadecimal numbers are 
written with a dollar sign preceding the value so that they can be distinguished from 
decimal values. Figure 5-7 provides a table of the hexadecimal digits and their decimal 
and binary equivalents: 



J 



Your 8502 microprocessor only understands the binary digits and 1 . Although machine 
language usually requires hexadecimal notation and BASIC processes decimal numbers, 
those numbers are translated and processed as binary numbers. Your computer uses 
three different number systems, binary (base 2), hexadecimal (base 16) and decimal 
(base 10). The machine-language monitor also uses the octal number base. A number 
base is also referred to as a radix; therefore, the C128 uses four radices, but the 
microprocessor only understands binary at machine level. 

BASIC understands decimal numbers because they are easiest for people to use. 
Although BASIC doesn't process as fast as machine language, the ease of use makes up 
for the loss of speed. 

Machine language uses hexadecimal notation because it is closer to the binary 
number system and easier to translate than decimal. Hexadecimal representation is also 
used usually by machine-level programmers because it is easier for people to think of a , 

group of eight binary digits (a whole byte) than it is to think of them as separate digits J 

by themselves. How do you find it easier to represent this value: 
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HEXADECIMAL 


DECIMAL 


BINAR1 


$0 





0000 


$1 


1 


0001 


$2 


2 


0010 


$3 


3 


0011 


$4 


4 


0100 


$5 


5 


0101 


$6 


6 


Olio 


$7 


7 


0111 


$8 


8 


1000 


$9 


9 


1001 


$A 


10 


1010 


$B 


11 


1011 


$C 


12 


1100 


$D 


13 


1101 


$E 


14 


1110 


$F 


15 


1111 



Figure 5-7. Hexadecimal/Decimal/Binary Conversion 



Each hex digit represents four bits. The highest number you can represent with 
four bits is 15 decimal. In machine language, you usually represent operands and 
addresses as two or four hex digits. Since each hex digit of a four-digit hexadecimal 
address takes up four bits, four of them represent 16 bits for addressing. 

At first you'll find yourself converting decimal addresses and operands into 
hexadecimal. Then you'll want to convert the other way. See the HEX$ and DEC 
functions for quick and easy decimal to HEX conversions. In the machine language 
monitor, use the ( + ) plus sign to represent decimal numbers. Use the conversions for 
now, but eventually you should find yourself thinking hexadecimal notation instead of 
always converting from decimal to hexadecimal. 



ADDRESSING MODES IN 
THE COMMODORE 128 

Addressing is the process by which the microprocessor references memory. The 8502 
microprocessor has many ways to address the internal locations in memory. The 
different addressing modes require either one, two or three bytes of storage depending 
on the instruction. Each instruction has a different version and op-code. For example, 
LDA (LoaD the Accumulator) has eight versions, each with a different op-code to 
specify the various addressing modes. See the 8502 Instruction and Addressing Table 
section for the different versions of all the 8502 machine-language instructions. 
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ACCUMULATOR ADDRESSING 

Accumulator addressing implies that the specified operation code operates on the 
accumulator. The operand field is omitted since the instruction can only perform the 
operation on the accumulator. Accumulator instructions require only one byte of stor- 
age. Here are some examples of accumulator addressing instructions: 



INSTRUCTION HEX OPCODE MEANING 

ASL $0A Shift one bit left 

LSR $4A Shift one bit riglit 

ROR $6A Rotate one bit right 



IMMEDIATE ADDRESSING 

Immediate addressing specifies that the operand be a constant value rather than the 
contents of a particular address. The operand is the data, not a pointer to the data. At 
machine level, the microprocessor actually interprets an operand field constant 
and an address in the operand field as two different op-codes, so the pound sign gives 
the programmer a way to distinguish between the data and a pointer to the data. 
Immediate addressing instructions require two bytes of storage. Here are some immedi- 
ate addressing instruction examples: 



INSTRUCTION HEX OPCODE MEANING 

Load the accumulator with 15 ($0F) 
Compare the accumulator with 255 ($FF) 
Subtract 224 ($E0) from accumulator 



LDA #$0F 


$A9 


CMP #$FF 


$C9 


SBC #$E0 


$E9 



ABSOLUTE ADDRESSING 



U 

u 

1 I 

u 
u 







u 



u 



Absolute addressing allows you to access any of the memory locations within either 64K 

RAM bank. Absolute addressing requires three bytes of storage; the first byte for the 

op-code, the second for the low byte of the address and the third for the high byte. Here I 

are some examples of absolute addressing instructions: LI 
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INSTRUCTION 


HEX OPCODE 


MEANING 


INC $4FFC 


$EE 


Increment the contents of address $4FFC by 1 


LDX $200C 


$AE 


Load the X register with the contents of address 
$200C 


JSR $FFC3 


$20 


Jump to location $FFC3 and save the return address 



ZERO-PAGE ADDRESSING 

Zero-page addressing requires two bytes of storage; the first byte is used for the opcode 
and the second for the zero-page address. Since zero page ranges from addresses 
through 255, the computer only needs the low byte to represent the actual address. The 
high byte is assumed to be 0; therefore, it is not specified. When addressing a zero-page 
location, you can still use absolute addressing; however, the execution time is not as fast 
as zero-page addressing. Here are some examples: 



INSTRUCTION 


HEX OPCODE 


MEANING 


LDA$FF 


$A5 


Load the accumulator with the contents of zero-page 
location $FF (255) 


ORA$E4 


$05 


OR the accumulator with the contents of location 

$E4 


ROR $0F 


$66 


Rotate the contents of location $0F one bit to the 
right 



IMPLIED ADDRESSING 

In implied addressing mode, no operand is specified because the op-code suggests the 
action to be taken. Since no address or operand is specified, an implied instruction 
requires only one byte for the op-code. Some examples are: 



INSTRUCTION HEX OPCODE MEANING 

Decrement the contents of the X register 
Increment the contents of the Y register 
Return from Subroutine 



DEX 


$CA 


INY 


$C8 


RTS 


$60 
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RELATIVE ADDRESSING 



LDA #$01 


.01800 A9 01 


LDA #$01 


STA TEMP 


.01802 85 FA 


STA $FA 


DEC TEMP 


.01804 C6 FA 


DEC $FA 


START BEQ START 


.01806 FO FC 


BEQ $1804 


LDX #$01 


.01808 A2 01 


LDX #$01 


STA COUNT 


.0180A 85 FB 


STA $FB 


(A) 


(B) 


(C) 


*NOTE: The machine language monitor does 


not provide for 


symbolic addresses and labels like TEMP and START. 



Figure 5-8. Relative Addressing 



Figure 5-8 lists the (A) code on the left as it appears in symbolic assembly 
language. The code (B) in the middle is the actual machine-level machine code 
as it appears in the machine language monitor. The (C) code to the right is the symbolic 
machine language as it appears in the monitor as executable code. 

In this program segment, the first instruction LoaDs the Accumulator with 1. 
STA is the op-code for STore the contents of the Accumulator in the variable 
TEMP. The third instruction, DEC, decrements the contents of the variable TEMP. In 
the third instruction, START is a label which marks the beginning of the conditional 
loop. The branch instruction (BEQ) checks to see if the value stored in TEMP equals 
as a result of the DECrement instruction. The instruction marks the end of the 
loop. 

The first time through this loop, the result in TEMP equals so program control 
branches back to the instruction specified by the label START. 

The second time through the loop, TEMP is less than zero; therefore, the zero 
flag in the status register is cleared, the program does not branch to START and 
continues with the statement direcfly following the branch instruction (LDX #$01). 



D 

U 
II 



Relative addressing is used exclusively with branch instructions. The branch instructions 
(BEQ, BNE, BCC, etc.) allow you to alter the execution path depending on a particular 
condition. Branch instructions are similar to IF . . . THEN statements in BASIC since 
they both conditionally perform a specified set of instructions. i "i 

The operand in the branch instruction determines the destination of the conditional I I 

branch. For example, the op-code BEQ stands for Branch on result EQual to zero. If the 
zero flag in the status register is equal to 1 add the operand to the program counter and 
continue execution at this new address. Figure 5-8 provides an example in symbolic ] 

assembly language. 



y 
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Because of the way this program segment is written, a branch can occur only once, the 
first time through the loop. 

Under relative addressing, the first byte of the instruction is the op-code and the 
second is the operand, representing an offset of a number of memory locations. The 
location to branch back to is not interpreted as an absolute address but an offset relative to 
the location of the branch instruction in memory. 

The offset ranges from -128 through 127. If the condition of the branch is met, 

the offset is added to the program counter and the program branches to the address in 

memory. 

i i In the example in Figure 5-8, notice that the operand in the branch instruction is 

only one instruction past the label START. The operand START is interpreted by the 

^ computer as an offset of three bytes backward in memory since the DEC instruction use 

I I 2 bytes and the BEQ op-code uses one byte. The 8502 can only branch forward 127 

bytes and branch backward by 128 bytes. 

If you enter the machine-language monitor and disassemble the machine-language 

' j code, you'll see how the computer represents a branch instruction operand as in part (B) 

I of Figure 5-8. The symbolic code in part (C) operand field represents the operands as 

absolute addresses but the assembled hexadecimal code to the left in part (B) of the op 

ncode stores the operand using one byte, a number plus or minus the address of the 
branch instruction. The largest number for a forward branch is $7F. A backward branch 
is represented by hex numbers greater than $80. When you are within the machine- 
p language monitor, subtract the operand offset from 255 ($FF) to find the actual value of 

I { the negative offset. In this case $FF minus 3 equals $FC, which is the operand in the 

branch instruction in part (B) of Figure 5-8. 

Here are some examples of relative addressing branch instructions: 



n 



INSTRUCTION HEX OP-CODE MEANING 



BEQ 


$F0 


Branch on result Equal to 


BNE 


$D0 


Branch on result Not Equal to 


BCC 


$90 


Branch on Carry Clear 



INDEXED ADDRESSING MODES 

The Commodore 128 has two special-purpose registers: the X and Y index registers. 
In indexing addressing modes, index registers modify an address by adding their 
contents to a base address to arrive at the actual or effective address. For example, 
here's a program segment that illustrates the importance of address modification, using 
the X and Y index registers: 
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LDA #$0F 
LDX #$00 
LOOP STA $2000,X 
INX 
BNE LOOP 



INSTRUCTION HEX OP-CODE MEANING 



INC operand, X $F6 Increment the contents of memory by 1. 

The base address (the operand) is added to the 
contents of the index register (X)). 

CMP operand,X $D5 Compare the contents of the accumulator with 

memory. The memory base address (the oper- 
and) is added to the contents of the bidex register 

(X)). 











u 



The first instruction in this program loads the accumulator with $0F(15 decimal). 
The second instruction loads the X register with 0. The third instruction stores the 
contents of the accumulator into the address $2000 added to the contents of the X index 
register. The first time the loop cycles, $0F is stored in address $2000 ($2000 + = i i 

$2000). The next instruction (INX) increments the contents of the X register. The last M 

instruction in the loop branches to the statement specified by the label LOOP, which is 
the STA $2000, X instruction. The second time through the loop, $0F is stored in 
location $2001 ($2000 + 1). The third cycle of the loop stores $0F in location $2002, etc. 

The loop continues to cycle and stores $0F in consecutive locations until the X 
register equals 0. In other words, the loop circulates 256 times until the X register 
equals 0, since 255 plus 1 is represented as 0. This is because the extra bit is carried 
over to the ninth bit position, which doesn't exist in an eight-bit number, so the register 
is reset to zero. This is similar to when your car odometer is set at 99,999 miles. When 
you travel another mile the dial resets to 00,000. 

This example shows just one way to modify addresses with the index registers. 
The Commodore 128 has four indexed addressing modes: (1) indexed absolute address- 
ing (illustrated in the example just shown), (2) indexed zero-page addressing, (3) 
indexed indirect addressing, and (4) indirect indexed addressing. 



y 



INDEXED ZERO-PAGE ADDRESSING 

This type of addressing is similar to zero-page addressing except that the index registers s 

(X or Y) are used to modify addresses within page zero ($00 to $FF) of memory. Since ! 

zero-page addressing requires no high byte to represent the page number, this type of 
instruction requires only two bytes of memory. The effective (actual) address is calcu- , - 

lated by adding the contents of the index register to the low byte of the address in the f 

program counter. This addressing mode is faster and more efficient than using indexed 
absolute addressing in zero page. 

Here are some examples of indexed zero-page addressing instructions: | 
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INDEXED ABSOLUTE ADDRESSING 

Indexed absolute addressing allows you to access and modify any of the memory 
locations in each of the two 64K banks. The effective address is calculated by adding 
the contents of the index register (X or Y) to the high and low byte base address 
determined by the operand. Since absolute addressing can access any of the available 
memory locations, high and low bytes are required to form the 16-bit address. There- 
fore, this type of addressing requires three bytes. 

Here are some examples of indexed absolute addressing instructions: 



INSTRUCTION HEX OP-CODE MEANING 

AND operand,Y $39 Perform the logical AND operation on the 

accumulator and the contents of memory base 
address plus the contents of the register (Y). 



ASL operand,X $1E Shift the contents of the memory (the memory 

' t is the base address (the operand) added to the 

contents of the index register (X)) one bit to the 
n 'eft. 



' THE INDIRECT ADDRESSING CONCEPT 



So far you've learned that the computer calculates the effective address as the 
base address (in the program counter) plus the offset from the contents of the index 
registers if indexed addressing is used. Indirect addressing calculates the effective 
address differently. 

Think of indirect addressing as the address of an address. Here's an illustration 
using absolute indirect addressing: 

IMP ($0326) 



' ^ The above JuMP instruction is an example of absolute indirect addressing. This 

type of instruction requires three bytes: one for the op-code, one for the low byte and 
n one byte for the high byte of the 16-bit address. The parentheses indicate that indirect 

) I addressing is used. The second and third bytes of the IMP instruction specify the low and 

high byte of the address. The address in the operand field is only the low byte of the effective 
p address. The contents of the byte immediately following the address specified in the JMP 

J I instruction is automatically placed into the program counter as the high byte of the effective 

address. In this example, the contents of location $0326 and $0327 represent the address of 
^_, the actual instructions to be executed. For example, location $0326, the low byte of 

I I the effective address, contains the value $65 and location $0327, the high byte of the 

effective address, contains the value $F2. The high- and low-byte values are placed in 
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INDIRECT INDEXED ADDRESSING 

This mode, also called indirect Y addressing, is post-indexed, which means the adding 
of the index itself obtains the effective address. This mode operates on the principle of a 
base address and a displacement. Here's how it works. 

The first of two bytes is the op-code, the second is the operand, a pointer to a 



u 



the program counter as the address $F265, the actual address of the next instruction '"' 
the computer executes then is $F265. 

If the parentheses were not present, the assembler interprets the instruction ] j 

as an absolute addressing instruction. The computer would understand the low •— ' 
byte to be $26 and the high byte to be $03 and would JuMP to the instruction 

located at $0326 instead of the intended address of $F265. Since this is not the j j 

case, the high byte is automatically presumed to be the low byte address plus 1 U 
(the contents of $0327). 

The last two addressing modes, indirect indexed and indexed indirect, use the i 

same principle as absolute indirect addressing. Here's an explanation of each. j 
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INDEXED INDIRECT ADDRESSING 

Indexed indirect addressing is similar to absolute indirect, although it uses index 
registers to modify an address. This type of addressing, sometimes called indirect X 
addressing, requires two bytes of storage: the first byte is for the op-code and the second 
is for the operand which is used in the effective address calculation. The address 
specified in the second byte is added to the contents of the X register and the carry, if 
any, is ignored. The results point to an address in page zero in which its contents 
contain the low byte of the effective address. The zero page address plus 1 indicates the 
high byte of the effective address. Both locations in which the low and high bytes of the 
effective address are contained must be located in page zero, locations $00 through $FF. 
Here's an example: 

LDX #$04 
LDA #$00 
STA ($DF,X) 

The first line loads the X register with $04. Next, the accumulator is loaded with 
0. The third instruction stores zero in the effective address. Calculate the effective 
address by taking the base address $DF (not the contents of it) and add the contents of 
the X register ($04) to it, which equals $E3. The contents of location $E3 is the low 
byte of the effective address and the contents of $E4 is the high byte of the effective 
address. For example, the contents of address $E3 contain $56 and the contents of 
address $E4 contain $F3. Since the contents of $E3 is the low byte and the contents of 
$E4 is the high byte, the effective address is $F356. Indexed indirect addressing is 
referred to as pre-indexing because the indexing occurs before the effective address is r / 

actually obtained. Indirect X addressing is useful in addressing a series of pointers such ji 

as the zero-page memory of the Commodore 128. 
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zero-page memory address. The contents of the pointer and the contents of the Y 
register are added to arrive at the low byte of the effective address. The contents of the 
pointer act as the base address and the contents of the Y register act as the displacement. 
The carry, if any, is added to the memory location directly following the low-byte 
address which becomes the high byte of the effective address. This is true indexing, 
designed specifically for manipulating tables of data. In order to access different table 
values, just change the contents of the Y register since the base address is already 
established. Here's an example: 

LDY #$08 
LDA #$00 
STA ($EA),Y 

The first instruction loads the Y register with $08. The second instruction loads 
/ I the accumulator with 0. The third instruction stores the contents of the accumulator in 

the effective address. 

To find the effective address, add the contents of the zero page memory location 
(base address) specified in the instruction to the contents of the Y register (displace- 
ment). In this example, the contents of the address $EA equals $F0. Add $F0 to the 
contents of the Y register ($08) to arrive at $F8, the low byte of the effective address of 
the next instruction. The high byte of the effective address is obtained by adding the 
carry (none in this case) to the zero-page memory location immediately following the 
low-byte address. For example, location $F9 contains the value $3F. Since the low byte 
is $F8 and the high byte equals $3F, the effective address is $3FF8. 

Notice the difference between indirect indexed and indexed indirect addressing 
modes as they can be confusing. Remember, the most important difference between the 
two addressing modes is the way the effective address is calculated. Indexed indirect is 
X indexing, which is indexed prior to the arrival of the effective address. Indirect 
indexed is post-indexed with the Y register. 

You have just covered all the addressing modes in the Commodore 128. Each calls 
for different circumstances and you should use the correct mode whenever circum- 
stances dictate it to obtain optimal performance from the microprocessor. For example, 
use indexed zero-page addressing when you are manipulating zero-page locations in- 
stead of using indexed absolute. 



TYPES OF INSTRUCTIONS 

This section explains all the types of machine-language instructions available in the 
Commodore 128. They are first covered by type of instruction, such as REGISTER TO 
MEMORY and COMPARE instructions; then they are listed alphabetically by op-code 
mnemonic with all the different addressing options. This section provides important 
information on programming in machine language on the Commodore 128 (or any 
6502-based microcomputer). 
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Use this information as a reference for background on each instruction. Figure 5-9 
provides an alphabetized list of the 8502 microprocessor op-code mnemonics. For 
detailed, quick-reference information, see the following section for an alphabetic list of 
instructions, their hexadecimal op-codes, the different versions of the instructions for 
each addressing mode and the way they affect the flags in the status register. 



u 



8502 MICROPROCESSOR INSTRUCTION SET- 


ALPHABETIC SEQUENCE 


ADC 


Add Memory to Accumulator with Carry 


AND 


"AND" Memory with Accumulator 


ASL 


Shift Left One Bit (Memory or Accumulator) 


BCC 


Branch on Carry Clear 


BCS 


Branch on Carry Set 


BEQ 


Branch on Result Zero 


BIT 


Test Bits in Memory with Accumulator 


BMI 


Branch on Result Minus 


BNE 


Branch on Result not Zero 


BPL 


Branch on Result Plus 


BRK 


Force Break 


BVC 


Branch on Overflow Clear 


BVS 


Branch on Overflow Set 


CLC 


Clear Carry Flag 


CLD 


Clear Decimal Mode 


CLI 


Clear Interrupt Disable Bit 


CLV 


Clear Overflow Flag 


CMP 


Compare Memory and Accumulator 


CPX 


Compare Memory and Index X 


CPY 


Compare Memory and Index Y 


DEC 


Decrement Memory by One 


DEX 


Decrement Index X by One 


DEY 


Decrement Index Y by One 


EOR 


"Exclusive-Or" Memory with Accumulator 


INC 


Increment Memory by One 


INX 


Increment Index X by One 


INY 


Increment Index Y by One 


JMP 


Jump to New Location 


JSR 


Jump to New Location Saving Return Address 


LDA 


Load Accumulator with Memory 


LDX 


Load Index X with Memory 


LDY 


Load Index Y with Memory 


LSR 


Shift Right One Bit (Memory or Accumulator) 


NOP 


No Operation 
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8502 MICROPROCESSOR INSTRUCTION SET- 


1 1 


ALPHABETIC SEQUENCE (cont'd) 


I \ 


ORA 


"OR" Memory with Accumulator 




PHA 


Push Accumulator on Stack 


1 ! 


PHP 


Push Processor Status on Stack 


/ \ 


PLA 


Pull Accumulator from Stack 




PLP 


Pull Processor Status from Stack 


, 1 


ROL 


Rotate One Bit Left (Memory or Accumulator) 


i I 


ROR 


Rotate One Bit Right (Memory or Accumulator) 




RTI 


Return from Interrupt 


r*f 


RTS 


Return from Subroutine 


1 
i i 


SBC 


Subtract Memory from Accumulator with Borrow 




SEC 


Set Carry Flag 


t^ 


SED 


Set Decimal Mode 


n 


SEI 


Set Interrupt Disable Status 


i 


STA 


Store Accumulator in Memory 




SIX 


Store Index X in Memory 


n 


STY 


Store Index Y in Memory 


1 


TAX 


Transfer Accumulator to Index X 




TAY 


Transfer Accumulator to Index Y 


»-^ 


TSX 


Transfer Stack Pointer to Index X 


i 


TXA 


Transfer Index X to Accumulator 


i 


TXS 


Transfer Index X to Stack Pointer 




TYA 


Transfer Index Y to Accumulator 



r-i 
i I 



Figure 5-9. 8502 Op-Code Mnemonics 

REGISTER TO MEMORY 
INSTRUCTIONS 

The REGISTER TO MEMORY instructions are: 



LDA 


STA 


LDX 


STX 


LDY 


STY 



The register to memory instructions either place a value into the accumulator, X 
register or Y register from memory, or store a value from a register (A, X, or Y) into a 
memory address. 

LOADING THE ACCUMULATOR 

The first and most common instruction is LDA, LoaD the Accumulator. This places a value 
into the accumulator, the most powerful and active register in the microprocessor. The 
value is derived from the contents of a memory location or a constant. Here's an example: 
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LDA $2000 

This instruction loads the contents of the memory location $2000 (8192 decimal) 
into the accumulator. The value in the memory location $2000 remains the same. The 
value also remains in the accumulator until another value is placed there or another 
operation acts upon it. 

The previous example is just one of the addressing modes for loading the accumu- 
lator. Another form the LDA instruction can take is to load a constant. To load a 
constant into the accumulator, you must precede the dollar sign ($) with a pound sign 
(#). For readability, it's a good idea to place at least one space between the op-code and 
the operand but it is not necessary. Here's an example of loading a constant into the 
accumulator: 

LDA #$0A 

This loads the constant $0A (10 decimal) into the accumulator. Remember, 
precede a constant with a pound sign, or else the assembler interprets the instruction as 
the contents of a memory address. 

The LDX and LDY instructions work the same way as the LDA instruction. 
Again, you can load a constant or the contents of a memory address into the X and Y 
registers. Examples: 

LDX #$0A 
LDX $2000 
LDX #$FB 



COUNTER INSTRUCTIONS 

The COUNTER instructions are 



u 



u 



STORE: THE OPPOSITE OF LOAD 

You know how to place a value into a register, but how do you do the opposite? The 

STORE instruction performs the opposite of a load. It places a value from the A , j 

(accumulator), X, or Y registers into a specified memory address. As you learned in the j 

addressing section, the load, store and most other machine-language instructions have 

several versions, depending on the type of addressing used. Here's an example: 

STA $FC3E 

This stores the contents of the accumulator into memory location $FC3E. The 
contents of the accumulator remain the same until another instruction modifies it. The 
STX and STY instructions work the same way; they store the contents of the register 
into a specified memory address. There is no immediate version or pound sign version 
of the store command. 



u 



u 



u 



INC DEC 
INX DEX 
INY DEY 

Counter instructions can be used to keep track of or count the number of times an j 

event occurs. These instructions are used for mathematical manipulations or indexing a 



u 



n 
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series of addresses. The counter instruction, INC, increments the contents of a memory 
^^ address by a value of 1 each time it is encountered. These instructions are used primarily 

i I within a program loop and in conjunction with a branch instruction. Here's an example 

' ^ of a loop and how INC keeps track of a number of occurrences of an event: 



LDX #$00 
TXA 
START STA $2000,X 
INX 
BNE START 

The first instruction loads a into the X register. The second instruction transfers 
the contents of the X register into the accumulator (without erasing the X register). 
Instruction three stores the contents of the accumulator (0) into location $2000 the first 

; ! time through the loop. The fourth instruction increments the contents of the X register. 

The last instruction branches to the instruction specified by the label START, until the 

p^ value of the X register equals 0. 

' This program segment stores O's in an entire page (256 locations) starting at $2000 

and ending at $20FF. When the contents of the X register equals 255 and it is 
incremented again, it is reset to 0, since it can only hold an eight-bit number. When this 
occurs, the branch is skipped and the program continues with the instruction directly 
following the branch instruction. 

The INY instruction operates in the same way as INX, since it also only uses 
implied addressing. The INC instruction, on the other hand, uses several different 
addressing modes including absolute, which uses 16-bit addresses. With the INC 
instruction, you can count past the capacity of an 8-bit number, though you must 
separate the counter into a high byte and a low byte. For example, the low byte counts 
the increments of less than a page and the high byte keeps track of the number of pages. 
When low-byte counter is at 255 and is incremented, it is set back to 0. When this 
occurs, increment the high-byte counter. To count up to 260 (decimal), the high- 
byte value equals 1 and the low byte equals 4. Here's an equation to illustrate the point: 

(1 * 256) -I- 4 = 260 

Here's the machine-language code that does this: 

LDA #$00 

STA HIGH 

STA LOW 
LOOP INC LOW 

BNE LOOP 

INC HIGH 
LOOP 2 INC LOW 

LDA LOW 

CMP #$04 

BNE L00P2 

The DECrement instructions operate the same way as the increment instructions. 
They are the negative number counterparts of the increment counters. 
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COMPARE INSTRUCTIONS "^ 

The Commodore 128 has three compare instructions that check the contents of a register ] 

with the contents of memory. A compare operation can be used to determine which [_ 

instructions to execute as a result of a conditioned value. The compare instructions are: 

CMP 1 

CPX L 

CPY 

The CMP instruction compares the contents of the accumulator with the contents 
of the specified address in the instruction. Compare instructions essentially subtract 
memory from a register value but change neither — they just set status flags. CPX 
compares the contents of the X register with the specified address. CPY compares the 
contents of the Y register with the specified memory location. 

All three instructions have versions that will operate in immediate, zero-page and 
absolute addressing modes. This means you can compare the contents of a register 
(A,X, or Y) with the contents of a zero-page location, any other address above zero page, 
or against a constant. Here's an example: 

LDX #$00 
LDA #$00 
ONE STA $DF,X 
INX 

CPX #$0A \ j 

BNE ONE U 

The preceding program segment stores O's in 10 consecutive memory addresses 
starting at $DF. The first instruction loads the X register with 0, the second loads into | } 

the accumulator. The third instruction stores in location $DF plus the contents of the X Lj 

register. The fourth instruction increments the X register. The fifth instruction compares 
the contents of the X index register with the constant $0A (10 decimal). If the contents i < 

of the X register does not equal $0A, the program segment branches back to the store m 

instruction specified by the label ONE. After the loop cycles ten times, the X register 
and the constant $0A are equal. Therefore the processor does not take the branch 
and the program continues with the instruction immediately following BNE. \ j 

You can compare the value of a register with the contents of an absolute memory ^ 

address. Here's the same example as above using the contents of a memory address 
instead of a constant: I / 

LDA #$0A Li 
STA $FB 

LDX #$00 > I 

LDA #$00 I I 

ONE STA $DF,X ^ 
INX 

CPX $FB j 

BNE ONE L. 



n 
( 1 
I \ 
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Remember, if you want to compare numbers larger than eight bits can represent 
(greater than 255 decimal), you must separate the number into a low byte and a 
high byte. 

The BIT instruction can also be used for comparisons. See the logical instructions 
next. 

ARITHMETIC AND 
LOGICAL INSTRUCTIONS 

The accumulator is responsible for all mathematical and logical operations performed in 
your computer. The mathematical and logical instructions available in machine language are: 

ADC EOR 
AND ORA 
BIT SBC 

Here's what each instruction means: 

ADC — ^Add the contents of the specified memory address to the contents of the 
accumulator with a carry. It is considered a good programming practice to clear 
the carry bit with the CLC instruction before performing any addition. This avoids 
adding the carry into the result. 

AND — Perform the logical AND operation with the contents of the accumulator and the 
contents of the specified memory address. 

BIT — Compare the bits in the specified memory address with those in the accu- 
mulator. Bits 6 and 7 are transferred to the status register flags. Bit 7 is trans- 
ferred to the negative status flag bit and bit 6 is sent to the overflow status flag bit. 

EOR — Perform the exclusive OR operation with the contents of the specified memory 
address and the contents of the accumulator. 

ORA — ^Perform the logical OR operation with the contents of the specified memory 
address and the contents of the accumulator. 

SBC — Subtract the contents of the specified memory address from the contents of the 
accumulator with a borrow. (It is a good practice to set the carry flag before 
performing subtraction. This avoids subtracting the borrowed bit from the result.) 

ARITHMETIC INSTRUCTIONS 
(ADC, SBC) 

The addition and subtraction instructions are easy to understand. Here's an example: 

CLC 

LDA #$0A 
STA $FB 
ADC #$04 
SEC 

SBC #$06 
ADC $FB 
STA $FD 
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Contents of Memory Address = 10101001 
Contents of Accumulator = 10000011 

Result of the OR operation = 10101011 



u 



This program segment essentially performs the following mathematical operation: O 
(10 + 4)-6+10=18. 

The first instruction clears the carry bit. The second instruction loads the accumu- \ ( 

lator with $0A (10 decimal). The third instruction stores the value in address $FB for M 
later use. The fourth instruction adds the constant $04 to the value already in the 

accumulator. The SBC instruction subtracts the constant $06 from the contents of the ^ , 

accumulator. The next instruction, ADC $FB, adds the contents of memory location i ( 

$FB to the contents of the accumulator. The resulting value (18($12)) of all the '—' 
mathematical operations is stored in address $FD. 

LOGICAL INSTRUCTIONS Li 

(AND, EOR, AND ORA) 

These instructions operate on the contents of a memory address and a register. The AND , , 

operation is a binary (Boolean) algebra operation having two operands that can result in | ( 

one of two values, or 1. The only way an AND operation can result in a 1 is if both 
the operands equal 1; otherwise the result is 0. For example, the two operands are the 
contents of a specified memory address and the contents of the accumulator. Here's an 
illustration of this concept: U 

Memory address = 10001010 i / 

Accumulator = 11110010 [J 

Result of AND = 10000010 

As noted, the result of an AND operation is (true) 1 , only if the two operands are u 
equal to 1; otherwise the resuU is 0. Notice bit 7 (high-order bit) equals 1 because both 

bit 7's in the operands are 1 . The only other resulting bit equal to 1 is bit 1 , since both bit ^ ; 

I's are equal to 1. The rest of the bits are equal to zero since no other bit positions in jj 
both operands are equal to 1. A 1 and a equals 0, as does a and a 0. 

The Boolean OR works differently. The general rule is: , , 

If one of the operands equals 1 , the resulting Boolean value equals 1 . LJ 

For example, the two operands are the contents of a specified memory address and 
the contents of the accumulator. Each individual bit can be treated as an operand. Here's i I 

an illustration. ^ 



u 



For all the bit positions that equal one in either operand, the resulting value of that ^ 
bit position equals 1 . The result is 1 if either operand or both operands are equal to 1 . 

The exclusive OR works similarly to the OR operation, except if both operands 1 

equal 1, the result is zero. This suggests the following general rule: [_ 
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If either of the operands equals 1 , the resulting Boolean value is 1 , except if both 
operands are 1 , then the result equals 0. 



Here's an example using this rule: 



Contents of Memory Address = 10101001 
n Contents of Accumulator = 10000011 



Result of the exclusive OR = 00101010 

I I In this example, the operands are the same as in the previous OR example. Notice 

bits and 7 are now equal to since both operands are equal to 1 . All other bit values 

iP-( remain the same. 

( j 

' ' BIT 

The BIT instruction performs a logical AND operation on the contents of the specified 

Ij memory address and the contents of the accumulator, but the resulting value is not 

' > stored in the accumulator. Instead, the zero flag in the status register is set by the result 

of the operation. The BIT instruction compares the contents of the accumulator and the 
contents of the memory address, bit-for-bit. If the result of the operation of the 
accumulator being ANDed by a memory location is 0, then the zero flag (in the status 
register) is set to a 1 . Otherwise the zero flag is 0. 

Your machine language program can then act conditionally depending on the 
result of the zero flag in the status register. In addition, bits 7 and 6 from the specified 
memory address are moved into the negative-flag and overflow-flag bit positions in the 
status register, respectively. These flags can also be used to perform conditional 

rj instructions depending on the value of the flag. For example, the BIT instruction 

i 1 performs the following: 

n 7 

NV BDIZC 



Contents of Memory Address = 10101001 
Contents of Accumulator = 11001101 -> 1 



Result of BIT instruction = 10001001 Status Register 

(Not stored in accumulator) 

Since the resulting bit pattern is not 0, the zero flag in the status register is 0. 
In addition, bits 7 and 6 are placed in the bit positions of the negative and overflow 
flags, respectively, in the status register. Notice the result of the BIT instruction's AND 
operation is not stored in the accumulator. The original contents of the accumulator 
remain intact. See the following example of 2-bit pattern operands that result in when 
ANDed: 
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7 

NV BDIZC 



Contents of Memory Address = 01111010 \ f 

Contents of Accumulator = 10000100 -^0 1 1 M 

lj 

Result of BIT instruction = 00001000 Status Register , , 



BRANCHING INSTRUCTIONS 



BCC 


BNE 


BCS 


BPL 


BEQ 


BVC 


BMI 


BVS 



Here's what the conditional branch instructions mean. The phrases in parentheses 
are the literal translations of the op-code mnemonics. The remainder explains the 
meaning behind the op-codes. 



Uj 



This time the bit patterns result in 0. Therefore, the zero flag in the status register 
is set to 1 . Bits 7 and 6 are also placed into their respective negative and overflow status 
register bit positions from their positions in the memory location. j ' 

Now you know how each of the arithmetic and logical instructions operate. The i_j 

next section discusses branching instructions. Branching instructions are designed so 
you can conditionally execute a certain set of instructions, depending on the result of a r , 

condition. Many times the conditions are contingent on the results of an arithmetic or / 

logical operation, which affects the flags in the status register. The branching instruc- 
tions then act according to the flags in the status register. 



u 



The 8502 microprocessor has many conditional branching instructions. By definition, a i ] 

branch temporarily redirects the otherwise sequential execution of program instructions. jj 

It transfers control to a location of a machine-language instruction other than the one 
immediately following the branch instruction in memory. 

The conditional branch instructions cause the microprocessor to examine a particu- | | 

lar flag in the status register. The processor, depending on the value of the tested flag, *-J 

either takes the branch and transfers control of the program to another location or skips 
the branch and resumes with the instruction immediately following the branch. \ i 

Think of a conditional branch as a test. For example, if the condition passes the [J 

test, the program branches or shifts control to an instruction that is not the next 
sequential instruction in the computer's memory. If it fails the test, the branch is skipped 
and program control resumes with the instruction immediately following the branch j 

instruction in memory. Remember that program control can also be shifted to an Lj 

instruction that is out of sequential order if it fails a test. This means you can transfer 
control of the execution of your program depending on the conditions you create. You \ i 

may set a condition that branches if the value of a certain flag (operand) is zero. jJ 

In another instance, you may set a condition to branch if a specific flag is set 
to 1. 

The conditional branch instructions available in the 8502 microprocessor are: 



y 
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BCC — (Branch on Carry Clear) Branch if the Carry flag in the status register equals 0. 
BCS — (Branch on Carry Set) Branch if the Carry flag in the status register equals 1. 
BEQ — (Branch on result EQual zero) Branch if the zero flag in the status register equals 1 . 
BMI — (Branch on result Minus) Branch if the negative flag in the status register equals 1. 
BNE — (Branch on result Not Equal to zero) Branch if the zero flag in the status register 

equals 0. 
BPL — (Branch on result PLus) Branch if the negative flag in the status register equals 0. 
BVC — (Branch on oVerflow Clear) Branch if the overflow flag in the status register 

equals 0. 
BVS — (Branch on oVerflow Set) Branch if the overflow flag in the status register 

equals 1. 

As you can see, all branching instructions depend on the value of a flag in the 
status register. 

Here are some branching examples. 

READY. 

MONITOR 

PC SR AC XR YR SP 
; FBOOO 00 00 00 00 F8 



01828 


E6 


FA 


INC 


$FA 


0182A 


A5 


FA 


LDA 


$FA 


0182C 


DO 


02 


BNE 


S1830 


0182E 


ES 


FB 


INC 


$FB 


01830 


08 




I NY 





This program segment keeps track of the low and high pointers in $FA and $FB 
respectively. The first instruction (INC $FA) increments the low byte address pointer. 
Next, the contents of $FA is loaded into the accumulator. The branch instruction (BNE 
$1830) evaluates the value of the accumulator. If the value is not equal to zero, the 
branch is taken to the instruction located at address $1830 (INY). In this case the high 
byte pointer is not yet ready to be incremented, so the INC $FB instruction is skipped. If 
the value in the accumulator is equal to zero, the branch is skipped and the high byte 
address pointer is incremented. 

This is an example of the BPL (Branch on Result Plus) instruction. 



READY. 

MONITOR 

PC SR AC XR YR SP 

; FBOOO 00 00 00 00 F8 

. 01858 8E 00 D6 STX $D600 

. 0185B 2C 00 D6 BIT SD600 

. 0185E 10 FB BPL S185B 

. 01860 8D 01 D6 STA $D601 



This example is a routine that checks the update ready status bit for the 8563 
address register, and ensures that data is valid before writing a value to an 8563 register. 
The first instruction stores the contents of the X register, which was previously loaded 
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The TXS and TSX instructions transfer values from the X index register to the 
stack pointer and vice versa. This is useful if you need to take a value off the stack 
temporarily, in a mathematical operation (for example, to operate on it and then replace 
it on the stack). Another use is to take a value off the stack, place it in the X register for 
temporary storage, add a new value on the stack, and then place the old value back on 
top. This could be the case when you need to sort values in ascending order. 

SHIFT AND ROTATE INSTRUCTIONS 

The shift and rotate instructions manipulate the bits of the accumulator or memory. 
Following are the shift and rotate instructions used by the 8502 family of microprocessors: 



u 



i) 



with an 8563 register number, into the 8563 address register. The BIT instruction places 

bit 7 of location $D600 into the negative flag in the 8502 status register. The BPL 

instruction branches to the BIT instruction in location $185B as long as the value of the i / 

negative flag is equal to 0. To the 8563 chip, this means the data is not yet valid and [j 

cannot be written to or read from until bit 7 is set. This loop continues until the value of 

bit 7 is 1, then it is transferred to the negative flag. The result now becomes negative 

so the branch is skipped and control is passed to the next instruction in memory, which 

stores the data into the 8563 data register. Refer to Chapter 10, Writing to an 8563 U 

Register for an expanded version of this program. 

REGISTER TRANSFER INSTRUCTIONS \j 

Register transfer instructions move a value from one register (A, X, or Y) to another. 
This instruction is useful since it only requires one byte of memory and saves the \ 'i 

programmer the trouble of loading the value from one register and storing it in another. M 

The 8502 microprocessor has the following six register transfer instructions: 

TAX — ^Transfer contents of accumulator to X index register 

TAY — ^Transfer contents of accumulator to Y index register U 

TSX — ^Transfer the contents of the stack pointer to X index register 

TXA — ^Transfer the contents of X index register to the accumulator i j 

TYA — ^Transfer the contents of the Y index register to the accumulator 

TXS — ^Transfer the contents of the X register to the stack pointer 



a 



U 



U 



\ i 
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ASL— Shift the whole byte one bit to the left 

LSR— Shift the whole byte one bit to the right 

ROL— Rotate the whole byte one bit to the left j ' 

ROR — Rotate the whole byte one bit to the right Li 



\ i 



SHIFT INSTRUCTIONS 

The shift instructions are useful when evaluating the value of a single bit at a time in a jj 

series of bits that control your program. For example, a joystick read routine is an 

example that calls for the shift instruction. Locations $DC00 and $DC01 control the 

joystick direction (bits 0-3), and the joystick fire button (bit 4). One way to evaluate 1 j 

these values is to shift them to the right. This causes the value to be passed to the carry U 
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( 1 flag. If the carry flag is enabled (1), then the joystick is being pushed in the direction 

corresponding to that bit. Here is a joystick read routine that uses the LSR instruction to 
(— } evaluate the direction of the joystick: 

'■ i 

; I 

READY. 



I ! 
/ I 



( ! 
/ i 



n 



n 



PC 


SR AC XR 


YR SP 


; FBOOO 


00 00 00 


00 F8 


. 01800 


AD 


00 DC LDA 


$DCOO 


. 01803 


AO 


00 


LDY 


#$00 


. 01805 


A2 


00 


LDX 


#$00 


. 01807 


4A 




LSR 




. 01808 


BO 


01 


BCS 


$180B 


. 0180A 


88 




DEY 




. OiaOB 


4A 




LSR 




. 0180C 


BO 


01 


BCS 


$180F 


. 0180E 


C8 




INY 




. 0180F 


4A 




LSR 




. 01810 


BO 


01 


BCS 


$1813 


. 01812 


CA 




DEX 




. 01813 


4A 




LSR 




. 01814 


BO 


01 


BCS 


$1817 


. 01816 


E8 




I NX 




. 01817 


4A 




LSR 




. 01818 


86 


FA 


STX 


$FA 


. 0181A 


84 


FB 


STY 


$FB 


. 0181C 


60 




RTS 





n ROTATE INSTRUCTIONS 

I ' The rotate instructions operate a little differently. Instead of the shifted bit falling into 

the carry flag, the bit "falling off the edge" is placed in the carry bit, then the carry bit 

n is placed at the opposite end of the byte. For example, if the ROR (rotate right) 

I { instruction is specified, each bit is moved one position to the right. Now bit 7 is placed in 

the carry bit and the carry bit is rotated around to the left and placed in the bit 7 bit 
position. The ROL instruction operates in the same manner, except the rotation is 

I j leftward rather than to the right. See Figure 5-10 to visualize the rotation concept of the 

' ' ROR (rotate right) instruction: 

n Bit Position 



07654321 




Figure 5-10. Concept of ROR (Rotate Right) Instruction 
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SET AND CLEAR INSTRUCTIONS 

The set and clear instructions are designed to manipulate the bits (flags) within the status 
register and control certain conditions within the microprocessor. These are the set and 
clear instructions available in 8502 machine language: 

SEC Set the Carry Flag 
SED Set Decimal Mode 
SEI Set the Interrupt Disable Bit 

CLC Clear the Carry Flag 

CLD Clear Decimal Mode 

CLI Clear the Interrupt Disable Bit 

CLV Clear the Overflow Flag 

Each of these instructions applies to a flag in the status register that controls a 
particular microprocessor condition. Notice that each clear instruction has a counterpart 
which sets the condition, except for CLV (Clear Overflow Flag). The overflow flag can 
be set by the BIT instruction or from the result of a signed mathematical operation 
overflowing into the sign bit. 

Figure 5-1 1 shows the 8502 status register: 



km 



B|p|l |Z|C| PROCESSOR STATUS REO"P" 



.^CARRY 1 bTRUE 
■►ZERO 1 s RESULT ZERO 

■►IROOISABLE 1 s OISASLE 

■»• DECIMAL MODE 1 b TRUE 
*- BRK COMMAND 



-►OVERFLOW 
-►NEGATIVE 



1 bTRUE 
1 B NEQ 



u 
u 

Li 



Figure 5-11. 8502 Status Register 
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U 



The flags of the status register are set for various reasons. For example, set 
decimal mode when you want to perform calculations in binary coded decimal (BCD) 
notation rather than hexadecimal. Set the carry flag when you are performing subtrac- 
tion. Set the interrupt disable bit when you want to prevent interrupts from occurring. 
An example of a split screen, smooth scrolling raster interrupt routine is given at the end 
of Chapter 8. 

The clear instructions operate in the reverse of the set instructions. To make sure 
that a carry does not occur during an addition operation, clear the carry flag before 
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' adding two numbers in the accumulator. To perform mathematical operations in hexa- 

decimal or binary numbers, clear the decimal mode flag so that your calculations are not 
n mistakenly performed in binary coded decimal. Whenever the result of a signed mathe- 

I I matical operation overflows into the sign bit an overflow error occurs. To correct this, 

clear the overflow flag with the CLV op-code. 
I— J When a program requires interrupts, first set the interrupt disable bit (SEI) to 

I prevent interrupts from occurring. At the end of the interrupt initialization routine, issue 

the CLI (Clear Interrupt Disable bit) instruction to enable (allow) interrupts to occur. 

r] JUMP AND RETURN INSTRUCTIONS 

JUMP INSTRUCTIONS 

I I The 8502 processor makes use of two jump instructions: 



n 

I 

n 



JMP — ^Jump to new location 

JSR — ^Jump to new location Saving the Return address 

These instructions both redirect control of the microprocessor to a location other than 
the one immediately following it in memory. The first instruction, JMP, is a one-way trip 
to the location specified in the operand field, or the contents of it (indirect). For example: 

JMP $1800 

jumps to location $1800 and executes the instruction contained in that location. This is a 
direct jump. 

You can also jump indirectly. For example: 

JMP ($1800) 

jumps to the address specified in the contents of location $1800. For instance, location 
$1800 contains the value $FE and location $1801 contains the value $C0. Therefore, the 
above instruction jumps to location $COFE, and not location $1800. Jumping indirectly 
is always denoted by parentheses around the address in the operand field, and it means 
to jump to the location specified by the CONTENTS OF the address in the operand field. 
The JSR instruction calls subroutines and saves the return address to the stack, so 
when an RTS instruction is encountered at the end of the subroutine, the microprocessor 
knows where to resume processing in the main (calling) program. Program control 
resumes with the instruction in memory immediately following the JSR instruction. In 
short, JSR is a round trip, while JMP is one way. For example: 

. 01804 20 58 18 JSR $1858 
. 01807 A2 00 LDX #$0C 



jumps to the subroutine starting at location $1858. The return address is saved on the 
stack, so when the RTS instruction is encountered in this subroutine: 
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01858 8E 00 D6 STX $D600 

0185B 2C 00 D6 BIT SD600 

0185E 10 FB BPL $185B 

01860 8D 01 D6 STA $D601 

01863 60 RTS 



The term push means to place a value on the stack, while pull means to remove 
a value from the stack. The only values pushed or pulled on to or off the stack are the 
contents of the status register or the accumulator. The manipulation of the stack values 
is important to the programmer when processing interrupts. The Raster Interrupt Split 
Screen Program with Horizontal Scrolling section in Chapter 8 illustrates the manipula- 
tion of the stack values prior to returning from the interrupt. 

THE NOP INSTRUCTION 

The NOP instruction stands for no operation. It is often used to add space between 
program segments for readability. This instruction is not executable. 



U 



the processor resumes with the main program instruction (LDX #$0C) in location $1807. 

RETURN INSTRUCTIONS 

The 8502 instruction set has two return instructions: 

RTI — ^Return from Interrupt 

RTS — ^Return from Subroutine \ i 



u 

\ I 

u 



The first instruction returns from your interrupt service routine after the interrupt 
disable bit is cleared (CLI) and the interrupt occurs. The RTI is the last instruction in the 
interrupt service routine. The interrupt service routine is the series of instructions which J 

are performed on the occurrence of an interrupt. Refer to Chapter 8, Raster Interrupt '—' 

Split Screen Program with Horizontal Scrolling for a working example of an interrupt 
service routine. j I 

The RTS instruction is the last instruction in a machine language subroutine called ^J 

from BASIC or by the machine language JSR instruction. See the Jump instructions 
above for an example. , , 

STACK INSTRUCTIONS 

Four stack instructions are included in the 8502 instruction set to manipulate the values j 

on the stack. These instructions are as follows: Lj 

PHA — ^Push accumulator on the stack i i 

PHP — ^Push processor status on the stack M 

PLA — ^Pull accumulator from the stack 
PLP — Pull processor status from the stack 



u 



*w-l 
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I 

n 

n 



8502 INSTRUCTION AND 
ADDRESSING TABLE 



The next 16 pages contain the 8502 Instruction and Addressing Table. These are the 
conventions used in the table: 



n 



n 



1. 


OP-CODE 


2. 


Brief definition 


3. 


Operation notation 


4. 


Status flags 


5. 


Flags affected 


6. 


Addressing Modes 


7. 


Assembly language form 


8. 


OP-CODE (in hex) 


9. 


Number of bytes 


10. 


Number of instruction cycles 



The following notation applies to this summary: 



A 


Accumulator 


X,Y 


Index Registers 


M 


Memory 


P 


Processor Status Register 


S 


Stack Pointer 


y 


Change 


- 


No Change 


+ 


Add 


A 


Logical AND 


- 


Subtract 


-V- 


Logical Exclusive Or 


t 


Transfer from Stack 


i 


Transfer to Stack 


-»■ 


Transfer to 


«- 


Transfer from 


V 


Logical OR 


PC 


Program Counter 


PCH 


Program Counter High 


PCL 


Program Counter Low 


OPER 


OPERAND 


# 


IMMEDIATE ADDRESSING MODE 
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ADC Add memory to accumulator with carry 

Operation: A + M + C-*A, C 



ADC 



N 


E 


c 


I 


D 


V 


y 


y 


/ 


- 


- 


y 



ADDRESSING 


ASSEMBLY 


OP 


NO. 


NO. 


MODE 


LANGUAGE FORM 


CODE 


BYTES 


CYCLES 


Immediate 


ADC 


#Oper 


69 


2 


2 


Zero Page 


ADC 


Oper 


65 


2 


3 


Zero Page, X 


ADC 


Oper, X 


75 


2 


4 


Absolute 


ADC 


Oper 


6D 


3 


4 


Absolute, X 


ADC 


Oper, X 


7D 


3 


4* 


Absolute, Y 


ADC 


Oper, Y 


79 


3 


4* 


(Indirect, X) 


ADC 


(Oper, X) 


61 


2 


6 


(Indirect), Y 


ADC 


(Oper), Y 


71 


2 


5* 



' Add 1 if page boundary is crossed. 



u 
U 



AND 



"AND" memory with accumulator 



AND 



Logical AND to the accumulator 
Operation: A AM -> A 



N E C I D V 

J J - - - - 



ADDRESSING 


ASSEMBLY 


OP 


NO. 


NO. 


MODE 


LANGUAGE FORM 


CODE 


BYTES 


CYCLES 


Immediate 


AND 


#Oper 


29 


2 


2 


Zero Page 


AND 


Oper 


25 


2 


3 


Zero Page, X 


AND 


Oper, X 


35 


2 


4 


Absolute 


AND 


Oper 


2D 


3 


4 


Absolute, X 


AND 


Oper, X 


3D 


3 


4* 


Absolute, Y 


AND 


Oper, Y 


39 


3 


4* 


(Indirect, X) 


AND 


(Oper, X) 


21 


2 


6 


(Indirect), Y 


AND 


(Oper), Y 


31 


2 


5 



u 



'■ Add 1 if page boundary is crossed. 



u 



n 
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ASL ASL Shift Left One Bit (Memory or Accumulator) 

Operation: C <- |7|6|5|4|3|2ir]o1 <- N Z C I 



ADDRESSING 
MODE 



ASSEMBLY 
LANGUAGE FORM 



OP NO. NO. 

CODE BYTES CYCLES 



Accumulator 


ASL 


A 


OA 


1 


2 


Zero Page 


ASL 


Oper 


06 


2 


5 


Zero Page, X 


ASL 


Oper, X 


16 


2 


6 


Absolute 


ASL 


Oper 


OE 


3 


6 


Absolute, X 


ASL 


Oper, X 


IE 


3 


7 



ASL 



D V 

y / y - - - 



BCC BCC Branch on Carry Clear BCC 

Operation: Branch onC = NZCIDV 



ADDRESSING 
MODE 



ASSEMBLY 
LANGUAGE FORM 



Relative 



BCC Oper 



* Add 1 if branch occurs to same page. 

* Add 2 if branch occurs to different page. 



OP NO. NO. 

CODE BYTES CYCLES 



90 



2* 



BCS BCS Branch on carry set BCS 

Operation: Branch onC = l NZCIDV 



ADDRESSING 
MODE 



ASSEMBLY 
LANGUAGE FORM 



Relative 



BCS Oper 



* Add 1 if branch occurs to same page. 

* Add 2 if branch occurs to next page. 



OP NO. NO. 

CODE BYTES CYCLES 



BO 



2* 
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BEQ BEQ Branch on result zero BEQ 

Operation: Branch onZ^l NZCIDV 



ADDRESSING ASSEMBLY OP NO. NO. 

MODE LANGUAGE FORM CODE BYTES CYCLES 

Relative BEQ Oper FO 2 2* 

* Add 1 if branch occurs to same page. 

* Add 2 if branch occurs to next page. 

BIT BIT Test bits in memory with accumulator BIT 

Operation: A A M, M7 -> N, M« -> V 

Bit 6 and 7 are transferred to tlie status register. N Z C I D V 

If tlie result of AAM is zero then Z = 1, otherwise M7 / - - - M« 

Z =0 

ADDRESSING ASSEMBLY OP NO. NO. 

MODE LANGUAGE FORM CODE BYTES CYCLES 

Zero Page BIT Oper 24 2 3 

Absolute BIT Oper 2C 3 4 



BMI BMI Branch on result minus BMI 

Operation: Branch onN = l NZCIDV 



u 
u 



ADDRESSING ASSEMBLY OP NO. NO. 

MODE LANGUAGE FORM CODE BYTES CYCLES 

Relative BMI Oper 30 2 2* 



* Add 1 if branch occurs to same page. 

* Add 2 if branch occurs to different page. 



u 

BNE BNE Branch on result not zero BNE 

Operation: Branch onZ = NZCIDV | 



ADDRESSING ASSEMBLY OP NO. NO. 

MODE LANGUAGE FORM CODE BYTES CYCLES 



u 



Relative BNE Oper DO 2 2* 



* Add 1 if branch occurs to same page. 

* Add 2 if branch occurs to different page. 
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n 



n 
n 



n 



BPL BPL Branch on result plus BPL 

Operation: Branch onN = NZCIDV 



ADDRESSING 
MODE 


ASSEMBLY 
LANGUAGE FORM 


OP 
CODE 


NO. 
BYTES 


NO. 
CYCLES 


Relative 


BPL Oper 


10 


2 


2* 



* Add 1 if branch occurs to same page. 

* Add 2 if branch occurs to different page. 



BRK BRK Force Break BRK 

Operation: Forced Interrupt PC + 2iPj, NZCIDV 

ADDRESSING ASSEMBLY OP NO. NO. 

MODE LANGUAGE FORM CODE BYTES CYCLES 

Implied BRK 00 1 7 

1 . A BRK command cannot be masked by setting I. 

BVC BYC Branch on overflow clear BVC 

Operation: Branch onV = NZCIDV 



ADDRESSING ASSEMBLY OP NO. NO. 

MODE LANGUAGE FORM CODE BYTES CYCLES 



Relative BVC Oper 50 

* Add I if branch occurs to same page. 

* Add 2 if branch occurs to different page. 



BVS BVS Branch on overflow set BVS 

Operation: Branch onV=l NZCIDV 



ADDRESSING ASSEMBLY OP NO. NO. 

MODE LANGUAGE FORM CODE BYTES CYCLES 

Relative BVS Oper 70 2 2* 



* Add 1 if branch occurs to same page. 

* Add 2 if branch occurs to different page. 
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CLC 

Operation: -> C 


CLC Clear carry flag 

N Z C 

- - 


ADDRESSING 
MODE 


ASSEMBLY OP NO. NO. 
LANGUAGE FORM CODE BYTES CYCLES 


Implied 


CLC 18 1 2 



CLX> 

Operation: -» D 


CLO C/eor decimal mode 

N Z C 


ADDRESSING 
MODE 


ASSEMBLY OP NO. NO. 
LANGUAGE FORM CODE BYTES CYCLES 


Implied 


CLD D8 1 2 



CLC 






CLD 



u 



CLI 

Operation: -^ I 


CLI Clear Interrupt disable bit 

N Z C I 

- - - 


D V 


ADDRESSING 
MODE 


ASSEMBLY OP NO. NO. 
LANGUAGE FORM CODE BYTES CYCLES 




Implied 


CLI 58 1 2 





CLI 



u 

I 

U 



CLV 

Operation: -^ V 



ADDRESSING 
MODE 

Implied 



CLV Clear overflow flag 



ASSEMBLY 
LANGUAGE FORM 

CLV 



OP NO. NO. 

CODE BYTES CYCLES 

B8 1 2 



CLV 



N Z C I D 



V 





U 



u 



n 
n 



n 

n 

1 i 

n 



MACHINE LANGUAGE ON THE COMMODORE 128 167 



CMP 



CMP Compare memory and accumulator 



* Add I if page boundary is crossed. 



CMP 



Operation: A - M 










N Z C I D V 

J y J - - - 


ADDRESSING 


ASSEMBLY 


OP 


NO. 


NO. 


MODE 


LANGUAGE FORM 


CODE 


BYTES CYCLES 


Immediate 


CMP 


#Oper 


C9 


2 


2 


Zero Page 


CMP 


Oper 


C5 


2 


3 


Zero Page, X 


CMP 


Oper, X 


D5 


2 


4 


Absolute 


CMP 


Oper 


CD 


3 


4 


Absolute, X 


CMP 


Oper, X 


DD 


3 


4* 


Absolute, Y 


CMP 


Oper,Y 


D9 


3 


4* 


(Indirect, X) 


CMP 


(Oper, X) 


CI 


2 


6 


(Indirect), Y 


CMP 


(Oper), Y 


Dl 


2 


5* 



n 



CPX 

Operation: X - M 


CPX Compare 


Memory and Index X 

N Z C I 

y y y - 


D V 


ADDRESSING 
MODE 


ASSEMBLY 
LANGUAGE FORM 


OP 
CODE 


NO. NO. 
BYTES CYCLES 




Immediate 
Zero Page 
Absolute 


CPX #Oper 
CPX Oper 
CPX Oper 


EO 
£4 
EC 


2 2 

2 3 

3 4 





CPX 



CPY 

Operation: Y - M 


CPY Compare 


memory and index Y 

N Z C I 

J. J y - 


D 


V 


ADDRESSING 
MODE 


ASSEMBLY 
LANGUAGE FORM 


OP 
CODE 


NO. NO. 
BYTES CYCLES 




Immediate 
Zero Page 
Absolute 


CPY #Oper 
CPY Oper 
CPY Oper 


CO 

C4 
CC 


2 2 

2 3 

3 4 





CPY 
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DEC 

Operation: M - 1 — » 


DEC Decrement 
M 


memory by one 

N Z C I 

y / - - 


D V 


DEC 


ADDRESSING 
MODE 


ASSEMBLY 
LANGUAGE FORM 


OP 
CODE 


NO. NO. 
BYTES CYCLES 




Zero Page 
Zero Page, X 
Absolute 
Absolute, X 


DEC Oper 
DEC Oper, X 
DEC Oper 
DEC Oper, X 


C6 
D6 
CE 
DE 


2 5 

2 6 

3 6 

3 7 





u 



DEX 

Operation: X - 1 — » X 



DEX Decrement index X by one 



ADDRESSING 
MODE 


ASSEMBLY 
LANGUAGE FORM 


OP 
CODE 


NO. 
BYTES 


NO. 
CYCLES 


Implied 


DEX 


CA 


1 


2 



DEY 

Operation: Y - 1 



DEy Decrement index Y by one 

N Z 



ADDRESSING 
MODE 


ASSEMBLY 
LANGUAGE FORM 


OP 
CODE 


NO. 
BYTES 


NO. 
CYCLES 


Implied 


DEY 


88 


1 


2 



EOR EOR "Exclusive — Or" memory w/th occumu/ator 

Operation: A -»M-V- A N Z C I 

J J - - 



ADDRESSING 
MODE 



ASSEMBLY 
LANGUAGE FORM 



OP NO. NO. 

CODE BYTES CYCLES 



Immediate 


EOR 


#Oper 


49 


2 


2 


Zero Page 


EOR 


Oper 


45 


2 


3 


Zero Page, X 


EOR 


Oper, X 


55 


2 


4 


Absolute 


EOR 


Oper 


4D 


3 


4 


Absolute, X 


EOR 


Oper, X 


5D 


3 


4* 


Absolute, Y 


EOR 


Oper, Y 


59 


3 


4* 


(Indirect, X) 


EOR 


(Oper, X) 


41 


2 


6 


(Indirect), Y 


EOR 


(Oper), Y 


51 


2 


5* 



* Add 1 if page boundary is crossed. 



u 



DEX 



N Z C I D V 

y ^ - - - - 



DEY 



C I D V 



EOR 



D V 



U 

U 
LI 



u 



Li 
U 



u 
U 



n 



1 1 



n 
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INC 

Operation: M + 1 



INC Increment memory by one 



M 



N Z C 

y y - 



ADDRESSING 
MODE 


ASSEMBLY 
LANGUAGE FORM 


OP 
CODE 


NO. 
BYTES 


NO. 
CYCLES 


Zero Page 
Zero Page, X 
Absolute 
Absolute, X 


INC Oper 
INC Oper, X 
INC Oper 
INC Oper, X 


E6 
F6 

EE 
FE 


2 
2 
3 
3 


5 
6 
6 

7 



INX 

Operation: X + 1 



INX Increment Index X by one 



ADDRESSING 
MODE 


ASSEMBLY 
LANGUAGE FORM 


OP 
CODE 


NO. 
BYTES 


NO. 
CYCLES 


Implied 


INX 


E8 


1 


2 



INY 

Operation: Y + 1 



INY Increment Index Y by one 



ADDRESSING 
MODE 


ASSEMBLY 
LANGUAGE FORM 


OP 
CODE 


NO. 
BYTES 


NO. 
CYCLES 


Implied 


INY 


C8 


1 


2 



INC 



I D V 



INX 



N Z C I D V 

y / - - - - 



INY 



N Z C I D V 

y / - - - - 



•• 


JMP 

Operation: (PC + 
(PC + 


1) 
2) 


]MP]ump 

-*PCL 
-^PCH 


to new loc 


at/on 

N Z C I 


D V 


p^ 








ADDRESSING 
MODE 




ASSEMBLY 
LANGUAGE FORM 


OP 
CODE 


NO. NO. 
BYTES CYCLES 




1 


Absolute 
Indirect 




JMP Oper 
JMP (Oper) 


4C 
6C 


3 

3 5 





JMP 
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JSR 



Operation: PC + 2 i , (PC + 1) 

(PC + 2) -* PCH 



JSR Jump to new location saving return address 

PCL N Z C I 



ADDRESSING 
MODE 



Absolute 



ASSEMBLY 
LANGUAGE FORM 



JSR Oper 



OP NO. NO. 

CODE BYTES CYCLES 



20 



JSR 



u 



D V 



u 
U 



LDA 

Operation: M 



LDA Load accumulator with memory 

N 



LDA 



Z C I D V 



ADDRESSING 


ASSEMBLY 


OP 


NO. 


NO. 


MODE 


LANGUAGE FORM 


CODE 


BYTES 


CYCLES 


Immediate 


LDA 


#Oper 


A9 


2 


2 


Zero Page 


LDA 


Oper 


AS 


2 


3 


Zero Page, X 


LDA 


Oper, X 


B5 


2 


4 


Absolute 


LDA 


Oper 


AD 


3 


4 


Absolute, X 


LDA 


Oper, X 


BD 


3 


4* 


Absolute, Y 


LDA 


Oper, Y 


B9 


3 


4* 


(Indirect, X) 


LDA 


(Oper, X) 


Al 


2 


6 


(Indirect), Y 


LDA 


(Oper), Y 


Bl 


2 


5* 



■ Add 1 if page boundary is crossed. 



LDX 

Operation: M ^ X 



LDX Load index X with memory 

N 



ADDRESSING 
MODE 



ASSEMBLY 
LANGUAGE FORM 



OP NO. NO. 

CODE BYTES CYCLES 



Immediate 


LDX 


#Oper 


A2 


2 


2 


Zero Page 


LDX 


Oper 


A6 


2 


3 


Zero Page, Y 


LDX 


Oper, Y 


B6 


2 


4 


Absolute 


LDX 


Oper 


AE 


3 


4 


Absolute, Y 


LDX 


Oper,Y 


BE 


3 


4* 



Add I wiien page boundary is crossed. 



LDX 



Z C I D V 



u 
[} 
U 

u 

u 
u 

i 



n 
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LDY 

Operation: M - 



LDY Load index Y with memory 

N 



LDY 



* Add 1 when page boundary is crossed. 



Z C I D V 



ADDRESSING 


ASSEMBLY 


OP 


NO. 


NO. 


MODE 


LANGUAGE FORM 


CODE 


BYTES 


CYCLES 


Immediate 


LDY 


#Oper 


AO 


2 


2 


Zero Page 


LDY 


Oper 


A4 


2 


3 


Zero Page, X 


LDY 


Oper, X 


B4 


2 


4 


Absolute 


LDY 


Oper 


AC 


3 


4 


Absolute, X 


LDY 


Oper, X 


BC 


3 


4* 



n 



LSR 
Operation: - 



LSR Shift right one bit (memory or accumulator) 
C 



|7|6|5|4|3|2|lfol 



ADDRESSING 
MODE 



ASSEMBLY 
LANGUAGE FORM 



N 




z 



OP NO. NO. 

CODE BYTES CYCLES 



Accumulator 


LSR 


A 


4A 


1 


2 


Zero Page 


LSR 


Oper 


46 


2 


5 


Zero Page, X 


LSR 


Oper, X 


56 


2 


6 


Absolute 


LSR 


Oper 


4E 


3 


6 


Absolute, X 


LSR 


Oper, X 


5E 


3 


7 



LSR 



C I D V 



NOP 

Operation: No Operation (2 cycles) 



NOP No operation 



NOP 



N Z C I D V 



ADDRESSING 
MODE 


ASSEMBLY 
LANGUAGE FORM 


OP 
CODE 


NO. 
BYTES 


NO. 
CYCLES 


Implied 


NOP 


EA 


1 


2 
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ORA 

Operation: A V M 



ORA "OR" memory with accumulator 

A N Z C I D V 

^ J - - - - 



ADDRESSING 
MODE 



ASSEMBLY 
LANGUAGE FORM 



OP NO. NO. 

CODE BYTES CYCLES 



Immediate 


ORA 


#Oper 


09 


2 




2 


Zero Page 


ORA 


Oper 


05 


2 




3 


Zero Page, X 


ORA 


Oper, X 


15 


2 




4 


Absolute 


ORA 


Oper 


OD 


3 




4 


Absolute, X 


ORA 


Oper, X 


ID 


3 




4* 


Absolute, Y 


ORA 


Oper, Y 


19 


3 




4* 


(Indirect, X) 


ORA 


(Oper, X) 


01 


2 




6 


(Indirect), Y 


ORA 


(Oper), Y 


11 


2 




5 


* Add 1 on page crossing 












PHA 


PHA Push accumulator 


on stack 




Operation : A i 










N 


Z C 



ADDRESSING 
MODE 


ASSEMBLY 
LANGUAGE FORM 


OP 
CODE 


NO. 

BYTES 


NO. 
CYCLES 


Implied 


PHA 


48 


1 


3 



ORA 



u 
u 



u 



u 



PHA 



u 



PHP 

Operation: P | 



PLA 

Operation: A f 



PHP Push processor status on stack PHP 

N Z C I D V 



ADDRESSING 
MODE 


ASSEMBLY 
LANGUAGE FORM 


OP 
CODE 


NO. 
BYTES 


NO. 
CYCLES 


Implied 


PHP 


08 


1 


3 



PLA Pull accumulator from stack 

N 

y 



ADDRESSING 
MODE 


ASSEMBLY 
LANGUAGE FORM 


OP 
CODE 


NO. 
BYTES 


NO. 
CYCLES 


Implied 


PLA 


68 


1 


4 



PLA 







Z C I D V 



U 



n 



I ) 



n 



1 1 
i 1 
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■n 
1 ! 








1 1 


PLP 


PLP Pull processor status from stack 


PLP 


1 

1 


Operation: P f 


N Z C I D V 
From Stack 




! 1 


ADDRESSING 
MODE 


ASSEMBLY OP NO. NO. 
LANGUAGE FORM CODE BYTES CYCLES 






Implied 


PLP 28 1 4 





ROL 



Operation: 



ROL Rotate one bit left (memory or accumulator) 

M or A 

N Z C 

J J J 



7|6|5|4|3|2|l|ol *-|c]< — i 



ADDRESSING 
MODE 



ASSEMBLY 
LANGUAGE FORM 



OP NO. NO. 

CODE BYTES CYCLES 



Accumulator 


ROL 


A 


2A 


1 


2 


Zero Page 


ROL 


Oper 


26 


2 


5 


Zero Page, X 


ROL 


Oper, X 


36 


2 


6 


Absolute 


ROL 


Oper 


2E 


3 


6 


Absolute, X 


ROL 


Oper, X 


3E 


3 


7 



ROR 

Operation: 



ion;[c~k H 



ROR Rotate one bit right (memory or accumulator) 
*0 



6543211 



ADDRESSING 
MODE 



ASSEMBLY 
LANGUAGE FORM 



OP NO. NO. 

CODE BYTES CYCLES 



Accumulator 


ROR 


A 


6A 


1 


2 


Zero Page 


ROR 


Oper 


66 


2 


5 


Zero Page, X 


ROR 


Oper, X 


76 


2 


6 


Absolute 


ROR 


Oper 


6E 


3 


6 


Absolute, X 


ROR 


Oper,X 


7E 


3 


7 



ROL 



I D V 



ROR 



N Z C I D V 



I i 
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u 



RTI 

Operation: P f PC f 



RTI Return from interrupt 



RTI 



N 



Z C I D 
From Stack 



ADDRESSING 
MODE 


ASSEMBLY 
LANGUAGE FORM 


OP 
CODE 


NO. 
BYTES 


NO. 
CYCLES 


Implied 


RTI 


40 


1 


6 



u 



IJ 



RTS RTS Return from subroutine RTS 

Operation: PCt,PC + l-»PC NZCIDV 



ADDRESSING 
MODE 



Implied 



ASSEMBLY 
LANGUAGE FORM 



RTS 



OP NO. NO. 

CODE BYTES CYCLES 



60 



U 



U 



SBC 



Operation: A - M - C 
Note: C = Borrow 



SBC Subtract memory from accumulator with borrow 

A NZCIDV 

^ y J - - J 



SBC 



ADDRESSING 


ASSEMBLY 


OP 


NO. 


NO. 


MODE 


LANGUAGE FORM 


CODE 


BYTES 


CYCLES 


Immediate 


SBC 


#Oper 


E9 


2 


2 


Zero Page 


SBC 


Oper 


E5 


2 


3 


Zero Page, X 


SBC 


Oper, X 


F5 


2 


4 


Absolute 


SBC 


Oper 


ED 


3 


4 


Absolute, X 


SBC 


Oper, X 


FD 


3 


4* 


Absolute, Y 


SBC 


Oper, Y 


F9 


3 


4* 


(Indirect, X) 


SBC 


(Oper, X) 


El 


2 


6 


(Indirect), Y 


SBC 


(Oper), Y 


Fl 


2 


5* 


* Add 1 when page boundary is crossed. 
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SEC 

Operation: 1 -» C 



Implied 



SED 

Operation: 1 ^ D 



ADDRESSING 
MODE 



Implied 



SEi 

Operation: 1^1 



ADDRESSING 
MODE 



Implied 



SEC Set carry fag 



ADDRESSING ASSEMBLY 

MODE LANGUAGE FORM 



OP NO. NO. 

CODE BYTES CYCLES 



SEC 



38 1 



SED Set decimal mode 



ASSEMBLY 
LANGUAGE FORM 



OP NO. NO. 

CODE BYTES CYCLES 



SED 



F8 



SEI Set Interrupt disable status 



ASSEMBLY 
LANGUAGE FORM 



OP NO. NO. 

CODE BYTES CYCLES 



SEI 



78 



SEC 



N Z C I D V 



SED 



N X C I D V 



SEI 



N Z C I D V 



STA 

Operation: A -» M 



ADDRESSING 
MODE 



STA Store accumulator In memory 

N Z C I 



ASSEMBLY 
LANGUAGE FORM 



OP NO. NO. 

CODE BYTES CYCLES 



Zero Page 


STA 


Oper 


85 


2 


3 


Zero Page, X 


STA 


Oper, X 


95 


2 


4 


Absolute 


STA 


Oper 


8D 


3 


4 


Absolute, X 


STA 


Oper, X 


9D 


3 


5 


Absolute, Y 


STA 


Oper, Y 


99 


3 


5 


(Indirect, X) 


STA 


(Oper, X) 


81 


2 


6 


(Indirect), Y 


STA 


(Oper), Y 


91 


2 


6 



STA 



D V 
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STX 

Operation: X — > M 



STX Store index X in memory 



STX 



N Z C I D V 



ADDRESSING 
MODE 


ASSEMBLY 
LANGUAGE FORM 


OP 
CODE 


NO. 
BYTES 


NO. 
CYCLES 


Zero Page 
Zero Page, Y 
Absolute 


STX Oper 
STX Oper, Y 
STX Oper 


86 
96 

8E 


2 
2 
3 


3 
4 
4 



STY 

Operation: Y -» M 



STY Store index Y in memory 



STY 



N Z C I D V 



ADDRESSING 
MODE 


ASSEMBLY 
LANGUAGE FORM 


OP 
CODE 


NO. 
BYTES 


NO. 
CYCLES 


Zero Page 
Zero Page, X 
Absolute 


STY Oper 
STY Oper,X 
STY Oper 


84 
94 
8C 


2 
2 
3 


3 
4 
4 



TAX 

Operation: A — » X 



TAX Transfer accumulator to index X 



TAX 



N Z C I D V 

J ^ - - - - 



ADDRESSING 
MODE 


ASSEMBLY 
LANGUAGE FORM 


OP 
CODE 


NO. 
BYTES 


NO. 
CYCLES 


Implied 


TAX 


AA 


1 


2 



u 



u 



Q 



TAY 

Operation: A -» Y 


TAY Transfer accumulator to index Y 

N Z C I 

^ J - - 


D V 


ADDRESSING 
MODE 


ASSEMBLY OP 
LANGUAGE FORM CODE 


NO. NO. 
BYTES CYCLES 




Implied 


TAY A8 


1 2 





TAY 



u 



n 
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TSX 

Operation: S -» X 



TSX Transfer stack pointer to index X 



ADDRESSING 
MODE 


ASSEMBLY 
LANGUAGE FORM 


OP 
CODE 


NO. 
BYTES 


NO. 
CYCLES 


ImpUed 


TSX 


BA 


1 


2 



TSX 



N Z C I D V 



n 



n 



TXA 

Operation: X -» A 


TXA Transfer index X to accumulator 

N Z C I 

y y - - 


ADDRESSING 
MODE 


ASSEMBLY OP 
LANGUAGE FORM CODE 


NO. NO. 
BYTES CYCLES 


Implied 


TXA 8A 


1 2 



TXA 



D V 



TXS 

Operation: X-^S 


TXS Transfer index X to stack pointer 

N Z C I 


D V 








ADDRESSING 
MODE 


ASSEMBLY OP NO. NO. 
LANGUAGE FORM CODE BYTES CYCLES 




Implied 


TXS 9A 1 2 





TXS 



TYA 

Operation: Y - 



TYA Transfer index Y to occumu/otor 



ADDRESSING 
MODE 


ASSEMBLY 
LANGUAGE FORM 


OP 
CODE 


NO. 
BYTES 


NO. 
CYCLES 


Implied 


TYA 


98 


1 


2 



TYA 



N Z C I D V 

y / - - - - 
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INSTRUCTION ADDRESSING MODES AND 
RELATED EXECUTION TIMES (in clock cycles) 



u 






I 



s 
u 



U U Id 

a ^ i5 

o 2 2 

ei et BC 

U M U 

N N S 



ADC 

AND 

ASL 

BCC 

BCS 

BEQ 

BIT 

BMI 

BNE 

BPL 

BRK 

BVC 

BVS 

CLC 

CLD 

CLI 

CLV 

CMP 

CPX 

CPY 

DEC 

DEX 

DEY 

EOR 

INC 

INX 

INY 

JMP 

JSR 

LDA 

LDX 

LDY 

LSR 

NOP 

ORA 

PHA 

PHP 



2 3 4 
2 3 4 
5 6 



4 
6 



2 3 4 



^ 



X! > S 



4 
4 
4 
6 






as 



I I 

g" S 
- 5 



I I § 



4 4:1: 441 
4 4* 4* 

6 7 



4* 



4>i< 
7 



4* 



4« 



^* 4« 

4* 

4* . 

7 . 

. . 2 

4* 4* 

. . 3 

. . 3 



2** 
2** 
2** 

2** 
2** 
2** 

2** 
2** 



6 5* 
6 5* 



5* 



5* 



5* 



5* 



D 



y 



u 



n 
' I 
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n 



n 



, 1 



PLA 

PLP 

ROL 

ROR 

RTI 

RTS 

SBC 

SEC 

SED 

SEI 

STA 

SIX 

STY 

TAX 

TAY 

TSX 

TXA 

TXS 

TYA 



U td (d 
U U U 



2 

o 



S N N 



o 

en 
ea 
< 



O ^ 
CO o5 

5 ? 



1 s 









g g 



g 



ea 

■< 



5 6 
5 6 



2 3 4 



3 4 
3 
3 4 



6 7 
6 7 



4 4* 4* 



4 5 

4 
4 



6 5* 



6 6 



I! 



* Add one cycle if indexing across page boundary 
** Add one cycle if branch is taken. Add one additional if branching 
operation crosses page boundary 



A clock cycle is the speed at which the processor operates as determined by the 
number of bytes transferred from one internal logic component to another. The 8502 
operates at a default speed of 1 MHz, which is equivalent to 1,000,000 cycles per 
second. 
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Now that you know about addressing modes, types of instructions and opcodes, you 
need to know iiow to actually enter machine language instructions into the Commodore 
128 memory. The C128 offers three methods of inputting instructions so that they may 
be operated on by the microprocessor. You can enter machine language instructions by: 

1. Using the built-in machine language monitor (available in CI 28 mode only). 

2. POKEing the translated decimal opcode values into memory with a BASIC 
program (CI 28 and C64 modes). 

3. Using an additional software program called an assembler. 



u 



u 



u 







\ 







All three methods have advantages and disadvantages. For instance, the built-in 
machine language monitor is easy to use and allows you to program in machine 
language without any additional aids such as an assembler. It makes merging BASIC 
and machine language easy. In addition, you can save machine language programs as 
binary files with the monitor SAVE command. Since you are already working in an 
object code, there is no need to compile from source code into an object code, as is 
necessary with an assembler. 

Though these are powerful features, the monitor does not allow the use of symbolic 
operand names or commented code. The monitor produces executable (object) code; 
hence, no source files are produced. The resulting coded program contains actual 
(absolute) address references, whereas an assembler source code file allows the use of 
symbolic addresses and arguments as well as comments. When you display a machine 
language program in the monitor, you do not have the luxury of comments or symbolic 
address variables, so you really have to know what you are looking for when reading 
other people's code. On the other hand, an assembler source file must be compiled into U 

executable object code, then used often with an additional program called a loader. This 
requires three steps, whereas the monitor's machine language is ready to run as soon as 
you finish writing the program. 

The second method, POKEing translated decimal opcode data into memory with a 
BASIC program, is an alternative usually implemented only when the first two options ^ 

are not available. This is the case if you have no assembler and are writing a machine ( 

language routine in Commodore 64 mode, which does not make the built-in monitor ^ 

available to you. However, it is sometimes handy to POKE small routines from 
BASIC if the application program you are writing is more suited for BASIC and you "i | 

need the speed of machine language for only a small portion of the program (though for J 

the most part, this method is tedious, bulky and time-consuming). Use it only if you 
have no alternative, since once it is POKED into memory, you cannot display a listing : , 

of the machine language routine as in the monitor or the assembler. j 

This chapter explains how to enter machine language programs in the first two 
methods described above. The third method, using an assembler, requires an additional 
software package similar to the Commodore 64 Assembler Development System. For | ( 

specific details on how to enter machine language programs with the assembler, refer to Lj 

the manual that is packed with the assembler software package you buy. 

i 

U 
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ENTERING MACHINE LANGUAGE 
INSTRUCTIONS IN THE MONITOR 

Begin entering machine language instructions by entering the monitor from BASIC with 
the following command: 

MONITOR RETURN 

The Commodore 128 responds with the following display: 

MONITOR 

PC SR AC XR YR SP 
; FBOOO 00 00 00 00 F8 

These values indicate the contents of the microprocessor registers upon entering 
the monitor. The abbreviations and definitions of the register names are as follows: 

PC — ^Program Counter Marks the address of the current machine language 

instruction 
SR — Status Register Flags that alert the microprocessor of certain conditions 
AC — ^Accumulator Register for all mathematical operations 

XR — ^X Index Register Used for effective address modification 
YR — Y Index Register Same as X register 
SP — Staci( Pointer Indicates the address of the first available memory 

location on the stack 

Now you can begin to enter machine language instructions. The ASSEMBLE 
command within the monitor enters the instructions into the specified memory location. 
To enter instructions, follow the format of this example: 

A 01800 LDA #$00 

Make sure to leave at least one space between each of the fields. Here's what each 
part of the instruction means: 

<Assemble> <Address in memory where opcode is stored> <Opcode> <Operand> 

The A stands for ASSEMBLE an opcode. The second part (field) is the address 
where the opcode in the instruction is placed in the Commodore 128 memory. Notice 
the 5-digit hexadecimal number specifying the address. The leftmost digit (0-F) speci- 
fies the configuration of the Commodore 128 memory layout. This is the same as the 
BANK command in BASIC. 

Once the entire machine language program is entered, reference the address that is 
contained in the first instruction you entered to start execution of the program. Execute 
the program with the GO command in the monitor, or exit the monitor with the X 
(EXIT) command and issue the SYS command from BASIC. If you SYS to the start of 
the program, you must use the decimal equivalent of the hexadecimal address, which 
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appears in the first instruction you entered. You must have an RTS instruction at the end 
of the routine if you want to return to BASIC. Often, the Kemal must be resident in the 
current configuration in context in order to obtain results. 

The opcode is the 8502 instruction that is carried out by the microprocessor when i 

your program is running. See the 8502 Instruction Set Table in Chapter 5 for allowable 
instructions. 

The operand is the address or value that is acted upon by the opcode in the | 

instruction. If the operand field is preceded by a pound sign (#), the opcode will act 
upon a constant value. If no pound sign is specified, the microprocessor assumes the 
opcode will act upon an address. j ' 

Remember to separate each field in the instruction with at least one space. If you jj 

don't, the computer indicates that an error has occurred by displaying a question mark at 
the end of the instruction. ^ , 

Once a routine is displayed on the screen, the monitor allows shortcuts in entering 
instructions. To display a listing of a machine language program, issue the DISASSEM- 
BLE command as follows: 

D 04000 04010 RETURN 1 [ 

The "D" stands for disassemble. The first number (04000) specifies the starting 
memory location in which you want the contents displayed. The second number ^ 

specifies the end address in which to display. j 

Now for the shortcut. Since the address where the opcodes are stored is already on ^ 

the screen, you can simply move the cursor to the opcode field, type over the exist- 
ing opcode and operand on the screen, erase any unwanted characters and press ) 
RETURN . The computer registers the instruction in memory by displaying the |_ 
hexadecimal values for the opcode and operand directly to the left of the opcode 
mnemonic you just entered. This is a faster and easier way of entering machine- 
language routines, rather than typing the ASSEMBLE command and the address each 
time you enter an instruction. U 

EXECUTING (RUNNING) U 

YOUR MACHINE-LANGUAGE PROGRAM 

[j' 

Once you have finished entering your machine language routine, you may execute it in 
three different ways. Within the monitor, issue the GO or JUMP to Subroutine com- 
mand as follows: 

G F1800 (IMP) 
J F1800 (JSR) 

The G stands for GO, or go to the start address of the machine language program 
in memory, and begin executing it at the specified address. The value following the 
letter G refers to the start address of your routine. The J stands for Jump to Subrou- 
tine, similar to the JSR mnemonic in machine language. j ) 

The third way to invoke a machine language routine is to exit the monitor by |J 
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pressing the X key and RETURN . This places you back within the control of the 
BASIC language. Next, issue the SYS command and reference the starting address in 
decimal as follows: 



' * BANK 15 

SYS 6144 



This SYS command is the same as the GO command (G F1800) example above. 
The BANK 15 command and the leading F in the 5-digit hexadecimal number F1800 
specify memory configuration 15. The Kemal, BASIC and other ROM code are 
resident in this configuration. The only difference is that it executes the machine 
language routine from BASIC, instead of within the monitor. 

The machine language routine given below clears the text screen. Starting at 

j-, location 1024 ($0400), the value 32 ($20) is stored in each screen location. The 

j j character string value 32 is the space character, which blanks out each character position 

on the screen. When finished, an RTS instruction returns control to BASIC. Here's the 

main BASIC program and the machine language screen-clear subroutine as it appears in 

Ij the machine language monitor. 



i j 10 FOR 1= 1 TO 25 

j 20 PRINT"FILL THE SCREEN WITH CHARACTERS" 

30 NEXT 

40 PRINT: PRINT 

50 PRINT"NOW CALL THE MACHINE LANGUAGE" 

: 60 PRINT" ROUTINE TO CLEAR THE SCREEN" 

[ 70 SLEEP 5 

' ' 80 SYS DEC("1800") 

90 PRINT"THE SCREEN IS NOW CLEARED" 



READY. 



MONITOR 






PC 


SR AC XR YR SP 




; FBOOO 


00 00 00 00 F8 




. 01800 


A2 00 LDX #$00 




. 01802 


A9 20 LDA #$20 




. 0X804 


9D 00 04 STA $0400 


x 


. 01807 


9D 00 05 STA $0500 


X 


. 0180A 


9D 00 06 STA $0600 


X 


. 0180D 


9D E7 06 STA $06E7 


X 


. 01810 


E8 INX 




. 01811 


DO Fl BNE $1804 




. 01813 


60 RTS 





In this sample program, the SYS command executes the subroutine to clear the 
text screen. Once the text screen is cleared, control of the microprocessor is returned to 
BASIC by the RTS instruction, and the READY prompt is displayed. 
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MACHINE LANGUAGE 
MONITOR COMMANDS 
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The C128's built-in machine language monitor has several additional commands that 
manipulate your machine language routines once they are entered into memory. Figure 
6-1 is a summary of all the commands available to you in the machine language 
MONITOR. 



IJ 



KEYWORD 
ASSEMBLE 

COMPARE 

DISASSEMBLE 

FILL 

GO 

HUNT 



GOSUB 
LOAD 

MEMORY 

REGISTERS 
SAVE 



TRANSFER 
VERIFY 

EXIT 

(period) 
(greater than) 
(semicolon) 



IWICTION 

Assembles a line of 8502 code A 

Compares two sections of mem- C 

ory and reports differences 

Disassembles a line or lines of 8502 D 

code 

Fills a range of memory with spec- F 

ifled byte 

Starts execution at the specified G 

address 

Hunts through memory within a H 

specified range for all occurrences 

of a set of bytes H 

Jumps to the subroutine J 

Loads a file from tape or disk L 

Displays the hexadecimal values M 
of memory locations 

Displays the 8502 registers R 

Saves to tape or disk S 



Transfers code from one section 

of memory to another 

Compares memory with tape or 

disk 

Exits Commodore 128 MONITOR 

Assembles a line of 8502 code 

Modifies memory 

Modifies 8502 register displays 



FORMAT 

<start address> <opcode> 

[operand] 

<start address> <end address> 

<new start address> 

[<start address> <end address>] 

<start address> <end address> 

<byte> 

[address] 

<start address> <end address> 
<bytel> [<byte n> . . .] 
<start address> <end address> 
<ascii string> 
[address] 

"<filename>"[,<device #> 
[,<load address>]] 
[<start address> 
[<end address>]] 

"<filename>",<device #>, 
<start address> <la$t address 
+ 1> 

<start address> <end address> 
<new start address> 
"<filename>"[,<device #>[, 
<load address>]] 



[address] 



1 ( 

u 



y 



U 
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KEYWORD 


FUNCTION 






FORMAT 


(at sign) 


Displays disk status, 


sends disk 


@ 






command, displays directory 








disk status 






©[device #] 




disk command 






©[device #],<command 
string>] 




disk catalog 






©[device #],$[[<drive>:<file 
speO]] 



NOTES <> enclose required parameters 
[] enclose optional parameters 



Figure 6-1. Summary of Commodore 128 Monitor Commands 



NOTE: 5-Digit Addresses 

The Commodore 128 displays 5-digit hexadecimal addresses within the 

machine language monitor. Normally, a hexadecimal number is only four 

digits, representing the allowable address range. The extra left-most (high 

order) digit specifies the BANK configuration (at the time the given 

command is executed) according to the following memory configuration 

table: 



i \ 



• 1 
I 1 



0— RAM only 

1— RAM 1 only 

2— RAM 2 only 

3— RAM 3 only 

4— INT ROM, RAM 0, I/O 

5— INT ROM, RAM 1, I/O 

6— INT ROM, RAM 2, I/O 

7— INT ROM, RAM 3, I/O 



8— EXT ROM, RAM 0, I/O 

9^EXT ROM, RAM 1, I/O 

A— EXT ROM, RAM 2, I/O 

B— EXT ROM, RAM 3, I/O 

C— KERNAL + INT (lo). RAM 0, I/O 

D— KERNAL + EXT (lo), RAM 1, I/O 

E— KERNAL + BASIC, RAM 0, CHARROM 

F— KERNAL + BASIC, RAM 0, I/O 



SUMMARY OF MONITOR 
FIELD DESCRIPTORS 

The following designators precede monitor data fields (e.g., memory dumps). When 
encountered as a command, these designators instruct the monitor to alter memory or 
register contents using the given data. 

<period> precedes lines of disassembled code. 
> <right angle> precedes lines of a memory dump. 
; <semicolon> precedes line of a register dump. 

The following designators precede number fields (e.g., address) and specify the radix 
(number base) of the value. Entered as commands, these designators instruct the monitor 
simply to display the given value in each of the four radices. 
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<null> (default) precedes hexadecimal values. 
$ <dollar> precedes hexadecimal (base- 16) values. 
+ <plus> precedes decimal (base- 10) values. 
& <ampersand> precedes octal (base-8) values. 
% <percent> precedes binary (base-2) values. 

The following characters are used by the monitor as field delimiters or line terminators 
(unless encountered within an ASCII string). 

<space> delimiter — separates two fields. 
, <comma> delimiter — separates two fields. 
: <colon> terminator — logical end of line. 
? <question> terminator — logical end of line. 

MONITOR COMMAND DESCRIPTIONS 

The following are descriptions of each of the C128 Machine Language Monitor commands. 



COMMAND: 
PURPOSE: 

SYNTAX: 



Enter a line of assembly code. 

A <address> <opcode mnemonic> <operand> 

<address> A number indicating the location in memory to 

place the opcode. (See 5-digit address note on 
previous page.) 
<opcode> A standard MOS technology assembly language 

mnemonic, e.g., LDA, STX, ROR. 
<operand> The operand, when required, can be any of the 

legal addresses or constants. 



A RETURN is used to indicate the end of the assembly line. If there are 
any errors on the line, a question mark is displayed to indicate an error, and the 
cursor moves to the next line. The screen editor can be used to correct the error(s) on 
that line. 

EXAMPLE: 

.A 01200 LDX #$00 
.A 01202 



I 1 



\ ( 

U 



u 
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NOTE: A period (.) is equal to the ASSEMBLE command. 



EXAMPLE: 

.02000 LDA #$23 
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COMMAND: 
PURPOSE: 

SYNTAX: 



Compare two areas of memory. 

C <ad(lress 1> <address 2> <a(ldress 3> 

<address 1> A number indicating the start address of the area 

of memory to compare against. 
<address 2> A number indicating the end address of the area 

of memory to compare against. 
<address 3> A number indicating the start address of the other 
area of memory to compare with. Addresses that 
do not agree are printed on the screen. 



n 



COMMAND: D 

PURPOSE: Disassemble machine code into assembly language mnemonics and 

operands. 
SYNTAX: D [<address>] [<address 2>] 

<address> A number setting the address to start the dis- 

assembly. 
<address 2> An optional ending address of code to be dis- 
assembled. 



I \ 
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The format of the disassembly differs slightly from the input format of an assembly. The 
difference is that the first character of a disassembly is a period rather than an A (for 
readability), and the hexadecimal value of the op-code is listed as well. 

A disassembly listing can be modified using the screen editor. Make any changes 
to the mnemonic or operand on the screen, then hit the carriage return. This enters the 
line and calls the assembler for further modifications. 

A disassembly can be paged. Typing aD RETURN causes the next page 
of disassembly to be displayed. 

EXAMPLE: 



LDA #$00 

??? 

BNE $3030 



D3000 3003 
.03000 A9 00 
.03002 FF 
.03003 DO 2B 

COMMAND: F 

PURPOSE: Fill a range of locations with a specified byte. 

SYNTAX: F <address 1> <address 2> <byte> 

<address 1> The first location to fill with the <byte>. 

<address 2> The last location to fill with the <byte>. 

<byte value> A 1- or 2-digit hexadecimal number to be written. 

This command is useful for initializing data structures or any other RAM area. 
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EXAMPLE: 



F0400 0518EA 

Fill memory locations from $0400 to $0518 with $EA (a NOP instruction). 



COMMAND: G 



PURPOSE: 
SYNTAX: 



Begin execution of a program at a specified address. 



[<address>] 
<address> 



An address where execution is to start. When 
address is left out, execution begins at the current 
PC. (The current PC can be viewed using the R 
command.) 



The GO command restores all registers (displayable by using the R command) and 
begins execution at the specified starting address. Caution is recommended in using the 
GO command. To return to the Commodore 128 MONITOR after executing a machine 
language program, use the BRK instruction at the end of the program. 

EXAMPLE: 

G 140C 

Execution begins at location $140C in configuration (BANK)O. Certain applica- 
tions may require that Kemal and/or I/O be present when execution begins. 
Precede the four-digit hexadecimal number with the hex configuration number 
which contains those appropriate portions of memory.) 

COMMAND: H 

PURPOSE: Hunt through memory within a specified range for all occurrences of a 

set of bytes. 
SYNTAX: H <address 1> <address 2> <data> 

<address 1 > Beginning address of hunt procedure. 
<address 2> Ending address of hunt procedure. 
<data> Data set to search for data may be hexadecimal 

for an ASCII string. 
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EXAMPLE: 



H AOOO A 101 A9 

Search for data $A9 from AOOO to AlOl. 

H2000 9800 'CASH' 

Search for the alpha string "CASH". 



COMMAND: 

PURPOSE: 

SYNTAX: 



Jump to a machine language subroutine. 
J <address> 



The JUMP to SUBROUTINE command directs program control to the machine language 



HOW TO ENTER MACHINE LANGUAGE PROGRAMS INTO THE COMMODORE 128 191 



n 



1 1 



n 
( I 

I I 



n 



n 

n 



subroutine located at the specified address. This command saves the return address as 
does the 8502 instruction JSR (Jump to Subroutine). In other words, the JUMP 
command is a two-way instruction, where the application gains control of the computer. 
Only after the subroutine encounters an RTS instruction does the machine language 
monitor regain control. 



EXAMPLE: 

J 2000 

Jump to the subroutine starting at $2000 in configuration 0. 

COMMAND: L 

PURPOSE: Load a file from cassette or disk. 

SYNTAX: L <"file name">[,<device>[,alt load address]] 

<"file name"> Any legal Commodore 128 file name. 

<device> A number indicating the device to load from. 1 is 

cassette. 8 is disk (or 9, A, etc.). 

[alt load address] Option to load a file to a specified address. 

The LOAD command causes a file to be loaded into memory. The starting address is 
contained in the first two bytes of the disk file (a program file). In other words, the 
LOAD command always loads a file into the same place it was saved from. This is very 
important in machine language work, since few programs are completely relocatable. 
The file is loaded into memory until the end of file (EOF) is found. 

EXAMPLE: 

L "PROGRAM", 8 Loads the file name PROGRAM from the disk. 
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COMMAND: M 

PURPOSE: To display memory as a hexadecimal and ASCII dump within the 

specified address range. 
SYNTAX: M [<address 1>] [<address 2>] 

<address 1 > First address of memory dump. Optional. If omit- 
ted, one page is displayed. The first digit is the 
bank number to be displayed, the next four digits 
are the first address to be displayed. 
<address 2> Last address of memory dump. Optional. If omit- 
ted, one page is displayed. The first digit is the 
bank number to be displayed; the next four digits 
are the ending address to be displayed. 

Memory is displayed in the following format: 

>1A048 41 42 43 44 45 46 47 48:ABCDEFGH 
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Memory contents may be edited using the screen editor. Move the cursor to the data to be 
modified, type the desired correction and hit RETURN . If a syntax error 
or an attempt to modify ROM has occurred, an error flag (?) is displayed. An 
ASCII dump of the data is displayed in reverse (to contrast with other data displayed on 
the screen) to the right of the hex data. When a character is not printable, it is displayed 
as a reverse period. As with the disassembly command, paging down is accom- 
plished by typing M and RETURN 
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EXAMPLE: 



M21C00 

>21C00 41 4A 4B 4C 4D 4E 4F 50 :AJKLMNOP 



NOTE: The above display is produced by the 40-column editor. 
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COMMAND: R 



PURPOSE: 



SYNTAX: 



Show important 8502 registers. The status register, the program counter, 
the accumulator, the X and Y index registers and the stack pointer are 
displayed. The data in these registers is copied into the microprocessor 
registers when a "G" or "J" command is issued. 
R 



U 

U 



EXAMPLE: 



PC SR AC XR YR SP 
; 01002 01 02 03 04 F6 



NOTE: ; (semicolon) can be used to modify register displays in the same 
fashion as > can be used to modify memory registers. 
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COMMAND: 

PURPOSE: 

SYNTAX: 



Save the contents of memory onto tape or disk. 

S <"filename">,<device>,<address 1>, <address 2> 

<"filename"> Any legal Commodore 128 filename. To save 
the data, the file name must be enclosed in dou- 
ble quotes. Single quotes cannot be used. 

<device> A number indicating on which device the file is 

to be placed. Cassette is 01; disk is 08, 09, etc. 

<address 1> Starting address of memory to be saved. 

<address 2> Ending address of memory to be saved -I- 1. All 
data up to, but not including, the byte of data at 
this address is saved. 



u 



I I 



HOW TO ENTER MACHINE LANGUAGE PROGRAMS INTO THE COMMODORE 128193 



n 



n 



The file created by this command is a program file. The first two bytes contain the 
starting address <address 1> of the data. The file may be recalled, using the L 
command. 

EXAMPLE: 

S "GAME",8,0400,0C00 

Saves memory from $0400 to $OBFF onto disk. 
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COMMAND: T 

PURPOSE: Transfer segments of memory from one memory area to another. 

SYNTAX: T <address 1> <address 2> <address 3> 

<address 1> Starting address of data to be moved. 

<address 2> Ending address of data to be moved. 

<address 3> Starting address of new location where data will 
be moved. 



n 
I 1 



Data can be moved from low memory to high memory and vice versa. Additional 
memory segments of any length can be moved forward or backward. An automatic 
"compare" is performed as each byte is transferred, and any differences are listed by 
address. 

EXAMPLE: 

T1400 1600 1401 

Shifts data from $1400 up to and including $1600 one byte higher in memory. 



n 



COMMAND: V 

PURPOSE: Verify a file on cassette or disk with the memory contents. 

SYNTAX: V <"filename">[,<device>][,alt start address] 

<"filename"> Any legal Commodore 128 file name. 

<device> A number indicating which device the file is on. 

Cassette is 01; disk is 08, 09, etc. 

[alt start address] Option to start vertification at this address. 

The VERIFY command compares a file to memory contents. If an error is found, the 
words VERIFY ERROR are displayed; if the file is successfully verified, the cursor 
reappears without any message. 



EXAMPLE: 

V"WORKLOAD",08 
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COMMAND: X 
PURPOSE: Exit to BASIC. 
SYNTAX: X 



COMMAND: 
PURPOSE: 

SYNTAX: 



COMMAND: 

PURPOSE: 

SYNTAX: 



> (greater than) 

Can be used to assign values for one to eight memory locations at a time 
(in 40-column mode; up to 16 in 80-column mode). 

> <address> <data byte 1> <data byte 2 . . . 8> 

<address> First memory address to set. 

<data byte 1> Data to be put at address. 

<data byte 2 . . . 8>Data to be placed in the successive memory 
locations following the first address (optional) 
with a space preceding each data byte. 

@ (at sign) 

Can be used to send commands to the disk drive. 

@ [<device number>], <disk cmd string> 

<device number> Device unit number (optional). 

<disk cmd string>String command to disk. 



NOTE: @ alone gives the status of the disk drive. 



EXAMPLES: 

@ 

@,I 

@,$ 
(»,$0:F* 



checks disk status 
00, OK, 00, 00 
initializes drive 8 

displays disk directory on unit 8. 

display all files on Drive 0, unit 8 starting with the letter F. 



As a further aid to programmers, the Kemal error message facility has been automati- 
cally enabled, while in the Monitor. This means the Kemal will display 'I/O ERROR#' 
and the error code, should there be any failed I/O attempt from the MONITOR. The 
message facility is turned off when exiting the MONITOR. 
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MANIPULATING TEXT WITHIN 

THE MACHINE LANGUAGE MONITOR 



Certain machine language application programs require the manipulation of strings of 
characters. If you are using an assembler package, it contains provisions for handling 
strings of characters. However, within the monitor, strings of characters must be placed 
in memory, either (1) through modifying a memory dump using the screen editor, or (2) 
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by placing the ASCII values of the characters in memory locations within a program. 

To modify a memory dump using the screen editor, issue the MEMORY com- 
mand with the address range in which you want to place the character string informa- 
tion. For example, suppose you want to place the word "TEXT" in memory starting at 
location $2000. First, enter the machine language monitor with the MONITOR com- 
mand. Next, issue the memory command containing the address $2000 as follows: 

M2000 

The 128 responds with this display: 

02000 FF 00 FF 00 FF 00 FF 00: ir.ir.ir.iT. 

The entire screen is filled with the contents of the memory (dump) locations $2000 
through $205F. For illustrative purposes, only one line of the memory dump is shown. 
This line pertains to the address range $2000 through $2007. At the right of the screen is 
an area that displays the corresponding ASCII character for each value within a memory 
location in that line of the memory dump. The left character in the display area 
corresponds to location $2000, the second character position to the right pertains to 
address $2001, and so on. To place the word "TEXT" in memory starting at location 
$2000, move the cursor up to the first line of the memory dump, move the cursor right 
to the memory address that pertains to address $2000, and place the ASCII character 
string code for the letter T in this position. To do this, type over the characters that are 
there and replace them with the hexadecimal equivalent of decimal 84 ($54) and press 
RETURN . Notice that the letter T is now displayed at the right of the screen. 
Refer to Appendix E, ASCII and CHR$ Codes, for a list of the Commodore ASCII 
codes for each character available in the Commodore 128. 

Now do the same procedure for the letters E, X and T. When you are through, the 
word "TEXT" is displayed in the display area. The first line of the memory dump now 
looks like this: 

02000 54 45 58 54 FF 00 FF 00: TEXT ir. ir. 



Now the character string you wish to manipulate is in memory, starting at address 
$2000. Your machine language routine can now act upon the characters of the word 
"TEXT" in order to display them on the screen. An efficient way of manipulating 
entire words is to use the start address in memory where the text begins, in this case 
$2000. Determine the length of the string, and use an index register as an offset to the 
end of the word. See the section Raster Interrupt Split Screen Program with Horizontal 
n Scrolling in Chapter 8, for a working example of manipulating text. This chapter has 

i described the use of machine language. For additional information on machine language 

topics, see Chapter 5, 7, 8, 9, 10, 11, and 13. 
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WHY MIX BASIC AND 
MACHINE LANGUAGE? 



ENTERING MACHINE LANGUAGE 
SUBROUTINES THROUGH BASIC 



u 
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Certain application programs are better suited for a high-level language such as BASIC 

rather than low-level machine language. In other cases, however, certain portions of a 

program, such as displaying graphics, may require the speed of machine language while 

the rest of the program lends itself to the use of BASIC. This is the main reason for 

mixing BASIC programs with machine language subroutines. Another reason may be i 

the lack of an alternative in programming machine language. For example, in C64 

mode, a machine language monitor is not ordinarily available to the user. In addition, 

you may not have an assembler package, so the only alternative is to enter machine 

language programs through the BASIC language. This method has disadvantages; it can 

be tedious and time-consuming, and once the routine is entered into memory, you have L 

no way of listing it to the screen for editing. This method is recommended only if no 

alternative is available. 



u 



In Chapter 6, you saw an example of how to use the SYS command to go from BASIC 
to a machine language routine that cleared the text screen. The SYS command invoked 
the subroutine, cleared the screen, and returned to BASIC with the RTS instruction. 
This example illustrated the SYS command within a program. You can also SYS to a 
machine language subroutine outside a BASIC program, as follows: — ' 

SYS 8192 

This example assumes you entered the machine language subroutine through the 
monitor (and it is still in memory). What if you don't have the monitor available to you, 
as in C64 mode, and you want to mix a machine language subroutine with a BASIC 
program? 

The answer to this is to POKE decimal data that represents the hexadecimal 
opcodes and operands into memory. To activate the subroutine, you SYS to it as you did 
before. This method of entering machine language programs requires these steps: 
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1 . Write your machine language program on a piece of paper. 

2. Translate the hexadecimal op-code values into decimal. Some instructions , 
require 3 bytes of memory, while others only use 1 or 2 bytes of memory. For 

a list of hexadecimal opcodes for the 8502 machine language instruction set, 
see the 8502 Instruction and Addressing Table, in Chapter 5. 

3. Enter the decimal equivalents of the opcodes into DATA statements in such a 

way that a 2-byte instruction, for example, is entered as follows: L 
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1000 DATA 162,0: REM = LDX #$00 = $A2, $00 



The hexadecimal number $A2 represents the 8502 instruction for LDX, which 
equals 162 in decimal. The (zero) represents the operand 0, which is 
loaded into the X register in the instruction. In hex, is the same as in 
decimal, so the second byte of the instruction is the operand value 0. The 
n hexadecimal opcodes are translated into strings of binary digits (bits), so the 

i i microprocessor can interpret and operate them. This is the true machine 

language of the computer at its lowest level. 

p 4. Once you have translated all the opcodes and operands into decimal, you 

i ; must place them in memory. Accomplish this by READing a DATA value in 

BASIC and POKEing it into memory in an appropriate address range. For 

example, to enter the LDX #$00 instruction into memory, in CI 28 mode, 

n perform the following routine: 

10 ALPHA = 8192 

201 = 

30 DO 
' ' 40 READ A 

45IFA=-999THENEXIT 
n 50 POKE ALPHA + I,A 

II 601 =1+1 

70 LOOP 

80 PRINT "ALL DATA IS NOW IN MEMORY" 



1000 DATA 162,0,-999 

For C64 mode use this routine: 

10 ALPHA = 8192 

20 FOR 1 = TO 1 

40 READ A 

50 POKE ALPHA + I,A 

60 NEXT 

80 PRINT "ALL DATA IS NOW IN MEMORY" 



1000 DATA 162,0 

The first example, in C128 mode, READs all DATA and POKEs it into 
memory, starting at location 8192 ($2000), until a data item is equal to -999. 
When the data item equals -999, EXIT the loop and print a message saying 
all the data is read into memory at the specified locations. This DO . . . 
LOOP allows you to enter as many data items as you please without the need 
to know how many data items are in the data list, since it checks for the 
terminator value -999. This programming approach makes it easy to modify 
the number of data entries without having to change any of the code. This 
program assumes that the bit map screen is not being used ($2000-$3FFF). 
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90 SYS 8192 

This command executes the machine language routine that you POKEd into 
memory starting at location 8192. 

Although the DATA statement in the example in Step 4 does not show it, all 
machine language subroutines must end with an RTS instruction so you can return to 
BASIC. The decimal code for an RTS machine language instruction is 96. Your last 
decimal data item in the final data statement in your program must be 96, unless you use 
a terminator like -999; then -999 will be your last decimal data item. 

Figure 7-1 shows a step-by-step translation from the machine language screen- 
clear routine as it appears in the monitor and a complete program that mixes the clear 
screen routine with the BASIC program that POKEs in the data and executes the 
machine language subroutine. It only operates in the 40-column (VIC) screen. 



u 



The second example, in C64 mode, uses a FOR. . . NEXT loop to 
enter the data. This requires you to know how many data items are in the data 
list. You can add an IF . . . THEN statement to check for a terminator value j 

like -999, as in the first example. However, this method illustrates a different L 

way of accomplishing the same thing. 
5. The final step in entering machine language subroutines through BASIC is , 

executing the subroutine with the SYS command. Add line 90 to your BASIC 
routines above as follows: 
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Symbolic 










Address 


Hej 


Opcode 




Instruction 






Decimal Equivalent 


















1st Byte 


2nd Byte 


3rd Byte 




A2 


00 




LDX 


#$00 


- 


(Opcode) 


(Operand) 




. 02000 


162 







. 02002 


A9 


20 




LDA 


#$20 


= 


169 


32 




. 02004 


9D 


00 


04 


STA 


$0400, X 


= 


157 





4 


. 02007 


9D 


00 


05 


STA 


$0500, X 


= 


157 





5 


. 0200A 


9D 


00 


06 


STA 


$0600, X 


=: 


157 





6 


. 0200D 


9D 


E7 


06 


STA 


$06E7,X 


= 


157 


231 


6 


. 02010 


E8 






INX 




s 


232 






. 02011 


DO 


Fl 




BNE 


$2004 


= 


208 


241 




. 02013 


60 






RTS 




= 


96 







Figure 7-1. Step-by-step Translation into Decimal 



To find the hexadecimal opcodes, refer to the 8502 Instruction and Address- 
ing Table in Chapter 5. Notice in Figure 7-1 that the hexadecimal opcodes are displayed 
within the monitor, directly to the left of the symbolic instruction. These hexadecimal 
numbers are the codes that you translate into decimal data items in a BASIC program. 

Notice that the second byte in the BNE instruction is the value 241. In a branch 
instruction, the operand is not an absolute address, but is instead an offset to the 
instruction to which it will branch. In this case, the BNE instruction branches backward 
to location $2004; therefore, it branches backward 15 locations in memory to the first 
store (STA) instruction. 

You're probably wondering how the code 241 tells the computer to branch 
backward by 15. The number 241 (decimal) is the 2's complement of the value 15. 
When bit 7 is enabled, the microprocessor branches backward. The number 241 
signifies to branch backward by 15 memory locations and execute the instruction in that 
location. To find the root value of a 2's complement number, do this: 

1. Translate the value into binary: 241 = 11110001 

2. Subtract 1: =1111 0000 = 240 

3. Convert each bit to its complement; in other words, 

change each bit to the opposite value: = 0000 1111 = 15 

To find the two's complement of a number, perform steps 1 and 3 above; 
then add 1 to the value instead of subtracting. 

Here's the complete C128 mode program, including all the decimal DATA 
equivalents of the instructions in the machine language, clear-screen subroutine above: 

10 ALPHA=8192 

20 1=0 

30 DO 

40 : READ A 

45 : IF A=-999 THEN EXIT 

50 : POKE ALPHA+I,A 

60 : 1=1+1 

70 LOOP 

80 PRINT"'ALL DATA IS NOW IN MEMORY" 

85 SLEEP 1 

90 SYS 8192 ^,, , 

1000 DATA 162,0,169,32,157,0,4,157,0,5,157,0,6,157,231,6 

2000 DATA 232,208,241,96,-999 
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Here is the corresponding program in C64: 



10 ALPHA=8192 

20 FOR 1=0 TO 19 

40 : READ A 

50 : POKE ALPHA+I,A 

60 NEXT 

80 PRINT"ALL DATA IS NOW IN MEMORY" 

85 FOR 1=1 TO 2500:NEXT 

90 SYS 8192 

1000 DATA 162,0,169,32,157,0,4,157,0,5,157,0,6,157,231,6 

2000 DATA 232,208,241,96 



When you run this program, the computer READs the DATA, POKEs it into 
memory, and executes the machine language, clear-screen subroutine with the SYS 
command. After you RUN the program, enter the machine language monitor (assuming 
you are currently in CI 28 mode) and disassemble the code in the range $2000 through 
$2015 with this command: 

D 2000 2015 

Notice that the subroutine you POKEd in through BASIC is the same as the 
subroutine that appears in Figure 7-1 . The two different methods accomplish the same 
goal — ^programming in 8502 machine language. 
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WHERE TO PLACE MACHINE 
LANGUAGE PROGRAMS IN MEMORY 

The Commodore 128 has 128K of RAM memory, divided into two 64K RAM banks. L 

Much of the 128K of RAM is overlaid by ROM, but not at the same time. The 

Commodore 128 memory is layered, so RAM is beneath the overlaid ROM. The 

designers of the Commodore 128 have managed to squeeze 28K of ROM and 128K of 

RAM into 128K of address space. Only one bank is available or mapped in at a time, 

since the highest address an 8-bit microprocessor can address is 65535 ($FFFF). , 

However, because the C128 is capable of banking RAM and ROM in and out so fast, it 

may seem as though 128K is always available. ^ 

In the portions of memory shared by RAM and ROM, a read operation returns a 
ROM data value and a write operation "bleeds through" to the RAM beneath the j 

layered ROM. The data is stored in the RAM memory location. If the data in RAM Li 

beneath the ROM is a program, the ROM on top must be switched out before the 
program in RAM can be executed. The RAM and ROM layout in memory is all j 

regulated and controlled through the Configuration Register (CR) of the Memory- L 
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Management Unit (MMU). For detailed information, refer to the sections on tlie 
Registers of the Memory Management Unit (specifically, the discussion of the Configu- 
ration Register) in Chapter 13. 

WHERE TO PLACE MACHINE LANGUAGE ROUTINES 
IN CONJUNCTION WITH BASIC 

Within BASIC, the operating system takes care of the mapping in and out of ROM and 
RAM. The CI 28 operating system provides sixteen (default) memory configurations. 
They each contain different values in the Configuration Register; therefore, each has a 
different configuration. This gives you sixteen different configurations of memory to 
choose from. Figure 7-2 lists the sixteen default memory configurations available under 
the control of the BASIC language. 





^ BANK 


CONnCURATION 





RAM(O) only 


1 


RAM(l) only 


2 


RAM(2) only 


1 3 


RAM(3) only 


! 4 


Internal ROM, RAM(O), I/O 


5 


Internal ROM, RAM(l), I/O 


-r ^ 


Internal ROM, RAM(2), I/O 




7 


Interna! ROM, RAM(3), I/O 




8 


External ROM, RAM(O), I/O 


9 


External ROM, RAM(l), I/O 


-' 10 


External ROM, RAM(2), I/O 


11 


External ROM, RAM(3), I/O 


' 12 


Kernal and Internal ROM (LOW), RAM(0), I/O 


13 


Kernal and External ROM (LOW), RAM(O), I/O 


1 14 


Kernal and BASIC ROM, RAM(O), Character ROM 




15 


Kernal and BASIC ROM, RAM(O), I/O 



Figure 7-2. Bank Configuration Table 

If you want to place a machine language subroutine in memory while the BASIC 
language is running, put the subroutine in a bank that contains RAM, preferably bank 
since this bank is composed entirely of RAM. If you place the machine language 
subroutine in a bank other than 0, not all of the RAM is available for pro- 
grams, since ROM overlays some of the RAM. You must check the value of the 
Configuration Register within that bank to see which addresses within these banks 
contain ROM. Check the value of the Configuration Register within each of the sixteen 
configurations and compare the value with the table in Figure 13-5 to see exactly where 
ROM maps in. 

Follow this procedure when calling machine language subroutines from BASIC: 



n 
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BANK 15 

3. Now call the subroutine with the SYS command. SYS to the start address 
where the first machine language instruction of your program is stored in 
memory. In this case, assume the subroutine starts at hex location $2000 
(assuming the VIC bit map screen is not used) and enter: 

SYS 8192 

The RAM in configuration in Figure 7-2 is the same RAM that appears in configura- 
tions (BANKS) 4, 8, 12, 13, 14, and 15. For example, you can enter programs into 
BANK 15, but you must make sure that no ROM overlays your program area. 



NOTE: If you plan to return to BASIC, make sure your subroutine ends 
with an RTS instruction. 



WHERE TO PLACE MACHINE LANGUAGE 
ROUTINES WHEN BASIC IS DISABLED 

When you are programming in machine language and you don't require the services of 
the BASIC ROM, you can disable BASIC by mapping out the BASIC ROMs. Do this 
by placing certain values into the Configuration Register in your own machine language 
routines as follows: 

LDA #$0E ;Set up the Configuration Register value 
STA $D501 ; Write to Preconfiguration Register A 
STA SFFOl ; Write to LCR A to change value of CR 
You can use this sequence: 



LDA #$0E 
STA $FF00 





u 



1 . Place the subroutine, preferably in bank 0, either through the monitor or by 
POKEing in the code through BASIC. If the Kemal, BASIC, and I/O are 
required, execute your program from configuration (BASIC Bank) 15. If you ] / 
enter the subroutine through the monitor, place the routine in bank by \_j 
placing the digit before the 4-digit hexadecimal address where the instruc- 
tions are stored. If you are POKEing the codes in through BASIC (not the , 
preferred method), issue the BANK command within your program, assum- i I 
ing you are placing the routine into BANK 0; then POKE in the decimal data 

for the opcodes and operands. The recommended memory range to place 
machine language routines in conjunction with BASIC is between $1300 and 
$1BFF. The upper part of BASIC text is also available, provided your BASIC 
program is small and does not overwrite your routine. 

2. Now, to process the rest of your BASIC program, return to bank 15 (the 
default bank) with this command: 
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When you switch out BASIC, the sixteen default configurations no longer exist L 
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via the BASIC command, so it becomes your responsibility to manage the memory 
configurations by manipulating the Configuration Register in your application program. 
Figure 13-5, on page 462, defines the values to place in the configuration register to 
arrive at the different memory configurations. 

When you switch out the BASIC ROMs, the address range where BASIC usually 
resides ($4000 through $7FFF for BASIC low and $8000 through $BFFF for BASIC 
high), is available for your machine language programs. Be careful when switching out 
the Kemal, since the Kemal controls the entire operation of the CI 28, including routines 
that seem transparent to the user (i.e., routines that you may take for granted). 

At certain points within your machine language programs, you may need to 
disable the I/O operation of the C128 temporarily. For instance, if you want to copy 
portions of the character ROM into RAM when programming your own characters, you 
must switch out the I/O registers $D000 through $DFFF of the C128, transfer the 
character data into RAM, and then switch the I/O back in. 

See the section discussing the Configuration Register, in Chapter 13, for a full 
explanation of how the C128 RAM and ROM memory is configured. 

This chapter has described the use of BASIC and machine language together. For 
material on using BASIC alone, see Chapters 2, 3 and 4. For material on using machine 
language see Chapters 5, 6, 8, 9, 10, 11 and 13. 
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THE RELATIONSHIP BETWEEN 
VIDEO BANKS, RAM BANKS 
AND MEMORY CONFIGURATIONS 



Many of you are familiar with how the Commodore 64 manages memory. This section 
explains how the Commodore 128 manages video memory, and how the video banks 
relate to the currently selected memory configuration. 











MANAGING BANKED MEMORY ^ 

Banking is a process in which a section of memory is addressed by the microprocessor. 
The memory is said to be banked in when it is available to the microprocessor in the 
current memory configuration. 

The Commodore 128 is programmable in its memory configuration. BASIC and - 

the Machine Language Monitor give you 16 pre-programmed default configurations of 
memory (referred to in BASIC as banks). For the purposes of this discussion, BASIC ^ 

banks are referred to simply as default memory configurations which are combinations 
of ROM and RAM in various ranges of memory. The current configuration, whether in | j 

BASIC or machine language, is determined by the value in the configuration register of U 

the CI 28 Memory Management Unit (MMU) chip. 

The sixteen different configurations in BASIC and the Machine Language Monitor 
require different values to be placed in the configuration register so that particular 
combinations of ROM and RAM can be banked into memory simultaneously. For 
example, the character ROM is only available in memory configuration 14 (Bank 14 in r , 

BASIC; the fifth digit hexadecimal prefix "E" in the Machine Language Monitor), | 

since this configuration tells the CI 28 MMU to swap out the I/O registers between 
$D000 and $DFFF, and replace them with the character ROM. To swap the I/O 
capabilities back in, change to any configuration number that contains I/O. Figure 8-1 j [ 

lists the sixteen default memory configurations available in BASIC and the Machine ^ 

Language Monitor. Information on programming the MMU is contained in Chapter 13, 
The Commodore 128 Operating System. 







THE TWO 64K RAM BANKS 

The Commodore 128 memory is composed of two RAM banks (labeled and 1), each ( 

having 64K of RAM, giving a total of 128K. The 8502 microprocessor address bus is 16 J 

bits wide, allowing it to address 65536 (64K) memory locations at a time. Figure 8-2 
illustrates the two separate 64K RAM banks. 

Although only 64K can be accessed at one time, the MMU has provisions for ( 

sharing up to 16K of common RAM between the two RAM banks. Common RAM is ^ 

discussed in Chapter 13. 

The 8502 microprocessor and the VIC chip can each access a different 64K RAM 
bank. The 8502 RAM bank is selected by the configuration register (bits 6 and 7) and 
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BANK CONFIGURATION 

RAM(O) only 

1 RAM(l) only 

2 RAM(2) only (same as 0) 

3 RAM(2) only (same as 1) 

4 Internal ROM , RAM(O), I/O 

5 Internal ROM , RAM(l), I/O 

6 Internal ROM , RAM(2), I/O (same as 4) 

7 Internal ROM , RAM(3), I/O (same as 5) 

8 External ROM , RAM(O), I/O 

9 External ROM , RAM(l), I/O 

10 External ROM , RAM(2), I/O (same as 8) 

11 External ROM , RAM(3), I/O (same as 9) 

12 Kernal and Internal ROM (LOW), RAM(O), I/O 

13 Kernal and External ROM (LOW), RAM(O), I/O 

14 Kernal and BASIC ROM, RAM(0), Character ROM 

15 Kernal and BASIC ROM, RAM(O), I/O 

Figure 8-1. CI 28 Default Memory Configurations 




►64K 



►64K 



Figure 8-2. CI 28 64K RAM Banks 



the VIC RAM bank is selected by the RAM configuration register (bits 6 and 7). This 
also is covered in detail in Chapter 13. 

The configuration determined by the configuration register can be composed of 
RAM and ROM, where the ROM portion overlays the RAM layer underneath, as 
illustrated in Figure 8-3. 
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Operation 













I ROM 


1 ROM 
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* 


RAM 





65535 



memory 
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U 



Figure 8-3. ROM Overlay 



A read (PEEK) operation returns a ROM value, and a write (POKE) operation 
bypasses the ROM and stores the value in the RAM underneath. 

Many different combinations of memory can be constructed to comprise a 64K 
configuration of accessible memory. Bits six and seven of the configuration register 
specify which RAM bank lies beneath the ROM layers specified by bits zero through 
five. The underlying RAM bank can be switched independently of any ROM layers on 
top. For instance, you may switch from RAM Bank to RAM Bank 1, while 
maintaining the Kemal, BASIC and I/O. 

I6K VIDEO BANKS 

In C128 graphics programming, a video bank is a 16K block of memory that contains 
the essential portions of memory controlling the CI 28 graphics system: screen and 
character memory. These two types of memory, which are discussed in the following 
section, must lie within the 16K range of memory referred to as a (VIC) video bank. 
The VIC chip is capable of addressing 16K of memory at any one time, so all graphics 
memory must be present in that 16K. Since the Commodore 128 microprocessor 
addresses 64K at a time, there are four video banks in each 64K RAM bank, or a total 
of eight video banks. (See Figure 8-4.) 

Where you place the VIC video bank depends on your application program. The 
Commodore 128 ROM operating system expects this bank in default video Bank 0, in 
the bottom of RAM Bank 0. Screen and character memory may be located at different 
positions within each 16K video bank, though in order to successfully program the VIC 
chip, the current 16K bank must contain screen and character memory in their entirety. 
You'll understand this after reading the next few pages. 
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video bank 3 



video bank 2 



video bank 1 



video bank 



video bank 3 



video bank 2 



video bank 1 



video bank 



►64K 



►64K 



Figure 8-4. Video Banl<s witliin RAM Banlcs 
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The four video banks in each 64K RAM bank are set up in the memory ranges 
specified in Figure 8-5: 



BANK 


1 

2 
3 



ADDRESS RANGE 

$0-$3FFF 

$4000-$7FFF 
$8000-$BFFF 
$COOO-$FFFF 



VALUE OF BITS 1 & IN $DDOO 
BINARY DECIMAL 

11= 3 (DEFAULT) 

10= 2 

01= 1 

00= 



Figure 8-5. Video Banl<s Memory Ranges 



Each RAM bank (0 and 1) has this memory layout. 

Bits and 1 of location $DDOO select the video bank. To select a video bank in 
BASIC, type this command: 

POKE 56576, (PEEK(56576) AND 252) OR X 

Where X is the decimal value of bits 1 and in Figure 8-5. 

In machine language, run the following program segment to select video banks: 

LDA $DDOO; load the accumulator with contents of $DDOO 

AND #$FC; preserve the upper 6 bits of $DDOO 

ORA #$X; where X is the hex value of bits 1 and from Figure 8-5 above 

STA $DDOO; Place the value in $DDOO 
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In the third instruction, replace X with the hexadecimal value of bits 1 and in L 

Figure 8-5. The default value is $03, which selects video bank zero. 

Whenever you change video banks, you must add $4000 to the address of your C / 

starting screen memory (video matrix) and character memory (bit map in bit map mode) [J 

for each bank above 0. To change to video Bank 1 , add $4000 to your starting screen 
and character address; for Bank 2 add $8000; for Bank 3 add $C(X)0. You must always 
add an offset of $4000 to the start of your screen and character memory for each video 
bank that is greater than zero. ^ 

SUMMARY OF BANKING CONCEPT [ 

L. 
The major features of the banking concept can be summarized as follows: 

1. BASIC and the Machine Language Monitor have sixteen 64K memory con- | 
figurations that give you sixteen different combinations of memory layouts. 

The MMU chip, particularly the value in the configuration register, controls 

most of the memory management in the Commodore 128. In order to PEEK | 

(read) from or POKE (write) to a particular portion of memory, you must L 

choose a BASIC or monitor configuration that contains the desired section of 

memory. Figure 8-1 lists the sixteen default memory configurations available i i 

in BASIC and the Machine Language Monitor. I J 

2. The 128K of memory is divided into two 64K RAM banks. Only one bank is 
addressable at a time by the microprocessor. RAM bank selection is con- 
trolled by the MMU configuration register (bits 6 and 7), which is part of the j 
C128 I/O memory. The VIC chip and 8502 microprocessor can each access a ^ 
different 64K RAM bank. Figure 8-2 illustrates the two separate and indepen- 
dent 64K RAM banks. f | 

3. Each 64K RAM bank is divided into four 16K video segments. The screen 
and character memory must both lie within the selected 16K video segment in 
order to successfully display graphics and characters on the screen. For each 
16K video bank higher than zero, remember to add $4000 (16384 decimal) to I f 
the start address of screen and character memory. Figure 8-4 shows how four Lj 
I6K video banks fit into each of the two 64K RAM banks. 

Here's how the banks fit together and operate within the Commodore 128. One j 

64K RAM bank is always mapped into memory. Within BASIC or the Machine 
Language Monitor, sixteen different memory configurations are available in a 64K bank. _ 

To change the configuration, issue the BASIC BANK command, or precede the four j [ 

digit hexadecimal address in the Machine Language Monitor with an additional hexadec- U 

imal digit through F. Outside of BASIC or the monitor, you can select other 
configurations, by changing the value in the configuration register at location $FFOO r , 

(or $D500). See Chapter 13 for details. j I 

Within the selected configuration, and part of the current 64K RAM bank, is a '^ 

16K range reserved for a video bank. The 16K video bank must encompass IK of screen 
memory, and either 4K of character ROM or an 8K block of memory for the bit map 
data. All these components must be present in order for graphics to operate. 
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In essence, the bank concept can be thought of in this way: The CI 28 has a 16K 
(VIC) video bank within a selected memory configuration within a 64K RAM bank. 

Figures 8-28 through 8-32 at the end of this chapter provides a graphics program- 
ming summary. 

SHADOW REGISTERS: INTERMEDIATE STORAGE 
LOCATIONS USED BY THE CI 28 SCREEN EDITOR 

Users who are experienced in programming the Commodore 64 VIC chip will find that 
most of the graphics operations of the Commodore 128 are performed in the same way 
as the C64. The main difference between the Commodore 64 and the Commodore 128 
graphics systems is the hardware implementation of split-screen modes. 
CI 28 mode provides two types of split-screen displays: 

1 . Standard character mode and bit map mode 

2. Standard character mode and multi-color bit map mode 

Because the split-screens switch from one display mode to another at a given 
time, the screen editor must be intemipt-driven. The interrupt indicates at what point 
the mode is to be switched. At that point, the VIC chip is loaded with preset values 
already contained in RAM. These preset values are known as shadow registers. Each 
time an interrupt occurs, certain video-chip registers are cleared and refreshed with the 
values in the shadow registers. These shadow registers add a variation in programming 
the VIC chip compared to the way the Commodore 64 handles it. 

The primary intermediate storage locations for VIC chip programming are: 



r 



NAME INDIRECT LOCATION ACTUAL LOCATION 

GRAPHM BIT 7 - 216 ($00D8) BIT 4 - 53270 ($D016) 

GRAPHM Bit 6 - 216 ($00D8) 

GRAPHM BIT 5 - 216 ($0OD8) BIT 5 - 53265 ($D011) 

VMl* BITS 7-4 - 2604 ($0A2C) BITS 7-4 - 53272 ($D018) 

VMl BITS 3-0 • 2604 ($0A2C) BITS 3-0 - 53272 ($D018) 

VM2** BITS 7-4 - 2605 ($0A2D) BITS 7-4 ■ 53272 ($D018) 

VM2 BITS 3-0 - 2605 ($0A2D) BITS 3-0 - 53272 ($D018) 



DESCRIPTION 

Multicolor Mode Bit 

Split Screen Bit 

Bit Map Mode Bit 

Video Matrix (screen memory) Pointer 

Character Base Pointer 

Video Matrix (screen memory) Pointer 

Bit Map Pointer 



*VM1 applies only lo standard and multi-color character (text) modes. 
**VM2 applies only lo standard and multi-color bit map modes. 
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You must store to and load from the indirect locations when accessing the above 
features of the VIC (8564) chip. For example, in C64 mode, this is how you set up the 
video matrix and bit map mode: 

10 POKE 53272, 120: REM Select bit map @ 8192, video matrix @ 7168 
20 POKE 53265, PEEK(53265) OR 32: REM Enter bit map mode 

Line 10 sets the video matrix at 7168 ($1C00) and the bit map at 8192 ($2000). 
Line 20 enables bit map mode. 

Normally, you would perform this operation with the high-level, 7.0 BASIC 
command: 

GRAPHIC 1 

The comparable way to accomplish this with POKE commands in CI 28 mode is 
as follows: 

10 POKE 2605,120 

20 POKE 216,PEEK(216) OR 32 

In CI 28 machine language, use these instructions: 

LDA #$78; set bit map @ $2000 

STA $0A2D; set video matrix @ 7168 

LDA $00D8 

ORA #$20 

STA $00D8; select bit map mode 

Although these examples do more than just select bit map mode and set up the 
video matrix and bit map pointer (such as wait on a video retrace when the raster is off 
the visible coordinate plane), these examples give you an idea of how to perform these 
programming steps. 

As you can see, CI 28 mode requires a slight variation in programming the VIC 
chip. You must keep this in mind when programming graphics in C128 mode. Usually, 
the high-level BASIC 7.0 commands take care of these variations. However, if you are 
programming in machine language, remember to address these indirect storage locations 
and not the actual ones. If you store values directly to the actual registers, the value will 
be cleared in a jiffy and no apparent action occurs. 

DrSABLING THE INTERRUPT DRIVEN 
SCREEN EDITOR 

You can disable the interrupt-driven CI 28 screen editor by storing the value 255 
($FF) in location 216 ($00D8). The actual VIC registers are not affected, and you 
can program the VIC chip the same way as the C64. This makes it unnecessary to 
address the indirect shadow registers. In BASIC, enter: 

POKE 216,255 

In machine language, you enter: 
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LDA #$FF 
STA $00D8 

Since disabling the interrupt allows you to program the VIC chip in the same way 
as the Commodore 64, you can store values directly to the actual registers. You do not 
have to address the indirect storage locations for VIC chip programming. However, if 
you don't disable the interrupt, it is still active and your values will be cleared upon the 
first occurrence of the raster interrupt. 

Remember, you must either disable the interrupt or address the indirect storage 
locations. Failure to do one or the other can cause serious problems in your program. 

The 80-column chip indirect memory locations are discussed in Chapter 10, 
Programming the 80-Column 8563 Chip. Certain other I/O functions require the use of 
indirect locations also. These are covered in Chapter 12, Input/Output Guide. 



THE COMMODORE 128 
GRAPHICS SYSTEM 

This section describes where the SCREEN, COLOR and CHARACTER memory com- 
ponents in the graphics system are located in character modes and bit map modes. 

Screen and character memory are addressed and stored differently in the character 
modes than in the bit-map modes. The split-screen modes use a section of both the 
character screen storage and the bit map screen storage. 

In graphics operations, the C128 can operate in either BASIC or machine language 
in both CI 28 and C64 modes. 

This section tells you where the graphics locations and screen color character 
memory are stored under each graphic mode. The next section details the inner workings 
of each graphic display mode including how color and data are assigned and how 
screen, color and character memory are interpreted. 

SCREEN MEMORY (RAM) 

The location in which screen RAM is stored in memory and the way the data are stored 
within it depends on the current graphics mode and operational mode of the CI 28. 

CI 28 BASIC 

In Commodore 128 BASIC, the character screen memory is located in the default address 
range 1024 ($0400) through 2023 ($07E7). The text screen memory can be moved. 
Remember, certain addresses use indirect memory locations to change the value of the 
actual address. The shadow register for the pointer to the text screen memory is location 
2604 ($0A2C). The actual location is 53272, but the screen editor uses a shadow since 
the VIC screen is interrupt-driven. A direct poke to 53272 ($D018) is changed back to 
its original value every sixtieth of a second. Here's how to change the location of screen 
memory in C128 BASIC: 
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POKE, 2604 (PEEK(2604) AND 15) OR X 

where X is a value in Figure 8-6. 

If you move the screen memory, make sure that the screen and character memory 
do not overlap. In addition, make sure to add an offset of $4000 to the start address of 
screen and character memory for each bank above 0. Additional commands are required 
to make the program work. Details follow in the discussion of each graphic mode, as 
well as program examples. 
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LOCATION* 


X 


BITS 


DECIMAL 


HEX 





ooooxxxx 





$0000 


16 


OOOIXXXX 


1024 


$0400 (DEFAULT) 


32 


OOIOXXXX 


2048 


$0800 


48 


OOllXXXX 


3072 


$0C00 


64 


OlOOXXXX 


4096 


$1000 


80 


OIOIXXXX 


5120 


$1400 


96 


OllOXXXX 


6144 


$1800 


112 


OlllXXXX 


7168 


$1C00 


128 


lOOOXXXX 


8192 


$2000 


144 


lOOlXXXX 


9216 


$2400 


160 


lOlOXXXX 


10240 


$2800 


176 


lOllXXXX 


11264 


$2C00 


192 


llOOXXXX 


12288 


$3000 


208 


IIOIXXXX 


13312 


$3400 


224 


lllOXXXX 


14336 


$3800 


240 


llllXXXX 


15360 


$3C00 



♦Remember that the BANK ADDRESS offset of $4000 per 
video bank must be added if changing to a higher video 
bank above 0. 

Figure 8-6. Screen Memory Locations 
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This register also controls where character memory is placed in memory. The 
upper four bits control the screen, the lower four control character memory. The "AND 
15" in the POKE 2604 statement ensures that the lower nybble is not upset. (If it had 
been, you would not see the correct character data.) 

In Commodore 128 bit map mode (standard or multi-color), the default bit map 
screen memory (video matrix) is located between 7168 ($1C00) and 8167 ($1FFF). 
Screen memory is interpreted differently in bit map mode than in text mode. The video 
matrix in bit map mode actually supplies color information to the bit map. This is 
explained in detail in the Standard Bit Map Mode section elsewhere in this chapter. To 
change the location of the bit map screen memory (video matrix), use this command: 

POKE 2605, (PEEK(2605) AND 15) OR X 
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where X is a value in Figure 8-6. Location 2605 is also a shadow register for 53272, but 
only for bit map mode. When you move the video matrix you must ensure that it does 
not overlap the bit map (data). In addition, be sure to add an offset of $4000 to the start 
address of the video matrix and the bit map for each video bank above zero. 

C64 BASIC 

In C64 mode, the text screen defaults to locations 1024 ($0400) through 2023 
($07E7). In bit map mode, the video matrix (screen memory) also defaults to this range 
though the screen memory is interpreted differently in either mode. Commodore 64 
BASIC allows you to move the location of the video matrix to any one of the sixteen 
locations specified in Figure 8-6. The upper four bits of location 53272 ($D018) control 
the location of the screen memory. To change the location of screen memory, use the 
following command: 

POKE 53272, (PEEK(53272) AND 15) OR X 

where X is equal to one of the values in Figure 8-6 



NOTE: The following paragraph pertains to both CI 28 and C64 modes. 



I ! 



Bits zero and one of location 56576 ($DDOO) control which of the four video 
banks is selected. The default bank is 0. If you change to another video bank (from to 
1, for example), then for each bank higher than bank zero, you must add an offset of 
$4000 to the starting video matrix (screen memory) address in Figure 8-6. This yields 
the actual address of the video matrix. For example, if you're changing from bank to 
bank 1, add $4000. If you are going to bank 2, add $8000; if you are changing to bank 
3, add $C000. Remember, this is true for both C128 and C64 modes. 

MACHINE LANGUAGE 

In machine language, use the commands listed under A in Figure 8-7 to move the C128 
(VIC) text screen. Use the commands under B to move the CI 28 bit map screen memory 
(video matrix). Use the commands under C to move the C64 text or bit map screen 
memory (video matrix). 



(A) 

MOVE C128 
TEXT SCREEN 

LDA $0A2C 
AND #$0F 
ORA#$X 
STA $0A2C 



(B) 

MOVE C128 
BIT MAP SCREEN 

LDA $0A2D 
AND #$0F 
ORA#$X 
STA $0A2D 



(C) 

MOVE C64 

TEXT OR BIT MAP 

SCREEN MEMORY 

LDA $D018 
AND #$0F 
ORA#$X 
STA $D018 



Figure 8-7. Moving Screen Memory in Machine Language 
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In Figure 8-7, X is the hexadecimal equivalent of the decimal value X in the left 
column in Figure 8-6. The second and third instructions in each example in Figure 
8-7 make sure not to upset the lower four bits of location 53272 or its shadow registers, , , 

2604 ($0A2C) and 2605 ($0A2D), since they control the character data for text and bit jl 

map modes. 



I 



u 



COLOR RAM 
CI 28 BASIC 

Color RAM within the Commodore 128 is always stationary in memory. It occupies the 
address range 55296 ($D800) through 56295 ($DBE7). In standard character mode, 
screen RAM and color RAM correspond to one another on a one-to-one basis. Location 
1024 gets color data from 55296, 1025 gets color from 55297 and so on. Multi-color 
character mode utilizes color RAM also, but in a different manner. Additional explana- 
tions and examples are provided in the Standard Character Mode section of this chapter. 

COLOR RAM BANKING 

In CI 28 mode, the LORAM and HIRAM signal lines allow the graphics system to 

make use of an additional Color RAM bank, which is not available in C64 mode. This 

allows fast and clean switching of colors for the character or multi-color bit map screen. \ ( 

The LORAM signal line allows the 8502 microprocessor to access one color RAM (J 

bank, while the HIRAM control line allows the VIC chip to access either Color RAM 

bank independendy of the microprocessor. Bit of location 1 controls the LORAM ; , 

signal line. LORAM selects color RAM bank or 1 as seen by the 8502 microprocessor \ 

depending on the value of the bit. If the bit value is low, the color RAM bank is 

accessed by the 8502. If the value of the bit is high, the upper color RAM bank is 

accessed by the 8502 microprocessor. j | 

Bit 1 of location 1 controls the HIRAM signal line. HIRAM selects color RAM i-J 

bank or 1 as seen by the VIC chip, depending on the value of the bit. If the bit value is 
low, the color RAM bank is accessed by the VIC chip. If the value of the bit is high, i j 

the upper color RAM bank 1 is accessed by the VIC chip. l_j 

These control lines add flexibility to the already powerful CI 28 graphics system. 
This allows you to change colors of the multi-color bit map or character screen on the fly, r 

without any time delay. It allows you to swap color RAM banks instantly. ) 

In standard bit map mode, color information is obtained from the bit map 
screen memory (the video matrix, $1C00 through $1FFF), not color memory. Bit ■ 

map mode interprets screen memory differently than character mode. Color RAM j 

is used in standard character mode, multi-color bit map mode, multi-color character "^ 

mode and the split-screen mode. 

C64 BASIC U 

In standard character mode, color RAM is located in the same place as in CI 28 mode: 

55296 ($D800) through 56295 ($DBE7). j j 

In bit map mode, C64 BASIC receives color information from screen memory (the jj 

\ ] 
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video matrix) as does CI 28 mode, though the default location for screen memory is 
1024 ($0400) through 2023 ($07E7). 

MACHINE LANGUAGE 

In machine language or in BASIC, standard character mode color data always comes 
from the same place. Color RAM is used for multi-color character mode. In 
standard bit map mode, however, color data originates from screen memory, so wher- 
ever you place screen memory, the color data for the bit map comes from the specified 
screen memory (video matrix) range. Multi-color bit map mode receives color from three 
places: color RAM, screen memory and background color register 0. This is explained in 
depth in the sections on the multi-color character and multi-color bit map modes. 

CHARACTER MEMORY (ROM) 

CI 28 BASIC-CHARACTER MODES 

In standard character mode, character information is stored in the character ROM in the 
memory range 53248 ($D000) through 57343 ($DFFF). In location 1 of the Com- 
modore 128 memory map, the CHAREN (CH ARacter ENable) signal determines whether 
the character set is available in any given video bank (0-3). Bit 2 of location 1 is the 
CHAREN bit. If the CHAREN bit is high (1), the Commodore character set is not 
available within the currently selected video bank in context. If the value of bit 2 in 
location 1 is low, equal to zero, then the CI 28 character set is available in the currently 
selected video bank. This is true in any of the four video banks in both 64K RAM 
banks. This feature allows the Commodore 128 character set to be available in any video 
bank at any time. To read the character ROM, enter BANK 14 either in BASIC or the 
MONITOR, and read the ROM, starting at location 53248. This configuration switches 
out I/O, and maps in character ROM in the range $D000 through $DFPT. Figure 8-8 
shows how the character sets are stored in the character ROM: 





ADDRESS 


VIC* 












BLOCK 


DECIMAL 


HEX 


IMAGE 


CONTENTS 





53248 


DOOO-DIFF 


lOOO-llFF 


Upper case characters 




53760 


D200-D3FF 


120O-13FF 


Graphics characters 




54272 


D40D-D5FF 


1400-15FF 


Reversed upper case characters 




54784 


D600-D7FF 


1600-17FF 


Reversed graphics characters 


1 


55296 


D800-D9Fr 


1800-19FF 


Lower case characters 




55808 


DAOO-DBFF 


lAOO-lBFF 


Upper case & graphics characters 




56320 


DCOO-DDFF 


ICOO-IDFF 


Reversed lower case characters 




56832 


DEOO-DFFF 


lEOO-lFFF 


Reversed upper case & graphics 
characters 


* = inC64 mode only 









Figure 8-8. Breakdown of Character Set Storage in Character ROM 
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The character memory is relocatable as is screen memory. To move standard 
character memory in CI 28 BASIC, alter the lower four bits (nybble) of location 2604 
($0A2C). Location 2604 is a shadow register for 53272 for the text screen memory 
(upper four bits) and character memory (lower four bits). To move the standard 
character memory use the following command: 



POKE 2604, (PEEK(2604) AND 240) OR Z. 

where Z is a value in Figure 8-9. 



u 






LOCATION OF CHARACTER MEMORY 


VALUE 










OFZ 


BITS 


DECIMAL 


HEX 







XXXXOOOX 





$0000-$07FF 




2 


XXXXOOIX 


2048 


$0800-$0FFF 




4 


XXXXOIOX 


4096 


SIOOO-SITFF 


ROM IMAGE in BANK & 2 
(default)* 


6 


XXXXOllX 


6144 


$1800-$1FF 


ROM IMAGE in BANK & 2* 


8 


XXXXIOOX 


8192 


$2000-$27FF 




10 


XXXXIOIX 


10240 


$2800-$2FFF 




12 


XXXXllOX 


12288 


$3000-$37FF 




14 


XXXXlllX 


14336 


$3800-$3FFF 




* = in 


C64 mode only. 









Figure 8-9. Character Memory Locations 



As with the other graphic system components, character data behaves differently in 
bit map mode than in text mode. 

Remember, the upper nybble controls where the screen memory maps in, so make 
sure not to upset those bits. The AND 240 in the POKE statement above takes care of 
preserving the upper four bits. 

In CI 28 mode the character sets are available in all video banks depending on the 
value of CHAR ENable 



NOTE: Remember to add an offset of $4000 to the start address of 
character memory, for each bank above 0; i.e., for bank 3 add 
3*$4000 = $C000 



U 



u 



u 
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CI 28 BASIC-BIT MAP MODES 

In bit map mode, the character memory data, also referred to as the bit map, defaults to 
Pi the range 8192 ($2000) to 16191 ($3F3F). The bit patterns of these 8000 bytes tell the 

; i computer which pixels to turn on. This block of memory "maps out" the picture on the 

screen, according to the data in this 8000-byte block. Since the standard bit map screen 
p* is 320 X 200, 64000 pixels make up the screen image. Divide 64000 by 8 to arrive at 

) j 8000 bytes of memory for the bit map. 

Besides the upper four bits for the video matrix, bit 3 of location 2605 ($0A2D) is 
^ the only significant bit in bit map mode. Location 2605 is the indirect memory location 

I ! of 53272 for bit map mode only. 

' * When you issue the GRAPHIC 1 command, bit 3 in 2605 is set. This specifies 

the bit map (data) to start at location 8192 ($2000). Whenever you enter bit map mode 
r| with the GRAPHIC command, bit 3 is always set. Outside of BASIC, you can specify 

/ 1 the bit map to start at location $0000; therefore, the value of bit 3 is zero. 

If the CI 28 is running under the control of CI 28 BASIC, the bit map always starts 

p on a boundary of $2000 (since bit 3 is set) within a given video bank. In video bank 

I I zero, the bit map starts at $2000. For banks 1, 2 and 3, the bit map begins at $6000, 

$A000 and $E000, respectively, since you must add an offset of $4000 for each bank 

number above zero. In machine language, however, bit 3 may have a value of zero or 

i| one. Therefore the bit map may start at $0000 if bit 3 is zero, or at $2000 if bit 3 is one, 

in each video bank. This means that the bit map has eight possible starting locations 

(per 64K RAM bank) in machine language— two for each of the four video banks. In 

C128 BASIC, the bit map can only start at one of the four locations. 

Don't forget to add the mandatory $4000 offset for each video bank above 0. The 
eight possible starting locations of a bit map in a machine language program are shown 
in Figure 8-10. 

This gives you the choice of eight starting locations in which to place your bit map 
data. Though only one bit map can fit in each video bank, you must leave room for the 
video matrix. Since the C128 has two RAM banks — each with four video banks per 
RAM bank — ^you may have a total of eight bit maps in memory, one for each video 
bank. Each video bank can fit only one bit map, because you need IK for screen RAM, 
and 8K for the bit map since a video bank has a maximum of 16K. To access another bit 
map, you must switch video banks. To access a bit map in the upper RAM bank (1), 
you may have to switch RAM banks and video banks. 



n 



n 
1 1 



VIDEO BANK 


VALUE OF BIT 3 = 







1 





$0000 


$2000 


1 


$4000 


$6000 


2 


$8000 


$A000 


3 


$C000 


$E000 



Figure 8-10. Starting Locations for Bit Map in Machine Language 



222 COMMODORE 128 



POKE 53272 (PEEK (53272) AND 240) OR Z 

where Z is zero if you want the bit map to start at $0000 in each bank, or Z = 8 if you 
want to place the bit map starting at 8192 ($2000) in each video bank. 

See Figure 8-10 for the arrangement of the bit map in each of the four 16K video 
banks within the two RAM banks. If you switch video banks, don't forget to add the 
$4000 (hex) offset for each bank above 0. See the Character Memory section under 
C128 Bit Map Mode in the last section for more detail on the arrangement of bit maps in 
memory. 



u 
u 






1) 



C64 BASIC-CHARACTER MODES 

In standard character mode in C64 BASIC, the lower four bits of location 53272 control 

where character memory is placed. As in C128 mode, the character ROM is actually 

mapped into memory between 53248 (SDOOO) and 57343 ($DFFF). The ROM image 

appears in RAM in the range 4096-8191 (in video bank 0) and 36864-40959 in bank 2, 

since it must be accessible to the VIC chip in a 16K range in video banks and 2. The 

character sets are not accessible in video banks 1 and 3. This ROM imaging in RAM 

applies only to character data as seen by the VIC chip. These memory ranges are still 

usable for data and programs and have no effect on the contents of RAM as far as your ^ j 

programs are concerned. |_J 

In C64 mode, the ROM image overlays the RAM underneath. A write operation 
"bleeds through" to the RAM underneath, while a read returns a ROM value depending 
on which memory configuration is currently in context. Since the VIC chip accesses | I 

16K at a time, the character set images must appear in the 16K which the VIC chip is 
currentiy addressing in video banks and 2. Remember, in C128 mode, the character 
sets are available in all video banks according to the value of the CHAREN bit in 
location 1. 

You can change the location of character memory with the following command: 

POKE 53272, (PEEK(53272) AND 240) OR Z Ij 

where Z is a decimal value in the table in Figure 8-9. 

The breakdown of the character sets is the same as in the CI 28 for the character \ j 

ROM (see Figure 8-8). ' ij 

C64 BASIC BIT MAP MODE [ j 

In bit map mode, bit 3 of location 53272 specifies the start of the bit map either at (_J 

$0000 or $2000 depending whether the value of bit 3 is or 1, respectively. Use the 
following command: 



u 



IJ 
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MACHINE LANGUAGE 

There are three ways to select the placement of character memory, as shown in Figure 
8-1 1 . Example A places character memory using the shadow register $0A2C in place of 
the actual $D018 register. Example B specifies the start of the bit map at $2000 (using 
shadow register $0A2D). Example C specifies the start of the C64 bit map or character 
memory. 



A 

LDA $02AC 

AND#$FO 
ORA #$Z 
STA $02AC 


B 

LDA $02AD 

AND #$F0 
ORA #$08 
STA $02AD 


c 

LDA $D018 

AND #$F0 
ORA #$Z 
STA $D018 



Figure ft-li. Selected Character Memory Location 



In Figure 8-11, Z is a value in the table in Figure 8-9. 



STANDARD CHARACTER MODE 



HOW TO ENTER STANDARD 
CHARACTER MODE 

The C128 powers up in standard character mode. This mode displays characters on the 
default screen. The character is displayed in a single color on a single color background. 
This is the mode in which you write (enter) programs. When you press RUN/STOP and 
RESTORE, the 0128 defaults to the text screen. 

Location 53265 (and its shadow register $00D8) determine whether the CI 28 is 
operating in standard character mode. If bit 5 is 0, as it is on power-up, the C128 is in 
character mode; otherwise it is in bit map mode. 

Location 53270 (and its shadow register $00D8) determine whether the characters 
are standard (single color) or multi-color. Bit 4 of 53270, and the shadow bit, bit 7 of 
$00D8, specify multi-color mode. If these bits are equal to zero, characters are standard; 
otherwise they are multi-color. See the Multi-color Character Mode section for more 
details on selecting multi-color character mode. 
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SCREEN LOCATION 



U 



In standard character mode, the screen memory defaults to the range 1024 ($0400) through 
2023 ($07E7). This is relocatable. See the Screen Memory section in the preceding pages. 

Since the screen is 40 columns by 25 lines, the text screen requires 1 ,000 memory 
locations to store all of the screen information in memory. The final twenty-four memory 
locations in screen memory do not store displayed data; they are used for other purposes. 
Each column of every row you see on the screen has its own screen memory location. 
The top-left screen location, referred to as HOME, is stored at address 1024 ($0400). 
The second screen location marked by the cursor is 1025 ($0401), and so on. Although 
the screen you see is constructed in rows and columns, the screen memory within the 
computer is stored linearly, starting at 1024 ($0400) and ending at location 2023 ($07E7). 

Figure 8-12 shows a screen memory map, so you can visualize how a screen memory 
location corresponds to the location on the physical screen of your video monitor. 

SCREEN MEMORY MAP 



II 



o 



y 



u 



COLUMN 

20 



u 



1063 



1024- 

1064 

1104 

1144 

1184 

1224 

1264 

1304 

1344 

1384 

1424 

1464 

1604 

1544 

1584 

1624 

1664 

1704 

1744 

1784 

1824 

1864 

1904 

1944 

1984 






f 
2023 



'J 



u 



u 



u 



Figure 8-12. Screen Memory Map 



HOW THE SCREEN MEMORY DATA 
IS INTERPRETED 

This screen memory range stores whole characters only. The characters are not repre- 
sented as ASCII character string codes (CHR$). Instead, they are stored in memory as 
screen codes as shown in Appendix D. The screen codes and character string codes are 



U 



n 



THE POWER BEHIND COMMODORE 128 GRAPHICS 225 



I I 



I 1 



n 



i I 



/ 1 



n 



n 



/ 1 



different due to the way they are stored in the character ROM. Notice in Appendix D 
that the screen code for an at-sign (@) is 0. The @ is numbered because it is the first 
character to be stored in the character ROM. The letter "A" is the second character 
ROM; therefore its code is 1. The letter "B" is the third character in the character 
ROM, etc. The screen code is actually an index from the starting location of the 
character ROM, beginning with zero. 

If you want to POKE a character directly into screen memory, use the screen code 
rather than the ASCII character string (CHR$) code. The same holds true for the 
machine language monitor. For example: 

POKE 1024,1 

places the letter A in the HOME position on the VIC screen. From the monitor, placing 
the value 1 in location $0400 (decimal 1024) also displays the letter A in the HOME 
position on the VIC screen. 

COLOR DATA 

In standard character mode, color information comes from color RAM, in the address 
range 55296 ($D800) through 56295 ($DBE7). This memory determines the color of the 
characters in each of the 1,000 screen locations. The background color of the screen is 
determined by the background color register which is location 53281. 

The color RAM and the screen RAM locations correspond on a one-to-one basis. 
Screen location 1024 pertains to color RAM location 55296; screen location 1025 
corresponds to color location 55297, etc. Figure 8-13 is the color RAM memory map. 
The map shows how color RAM corresponds to the locations in screen RAM and the 
placement on your video display. 

COLOR MEMORY MAP 



COLUMN 

20 



am 

1 



55296- 

55336 

55376 

5S416 

55456 

55496 

55536 

55576 

55616 

55656 

55696 

55736 

55776 

55816 

55856 

55896 

55936 

55976 

56016 

56056 

56096 

56136 

56176 

56216 

56256 






10 I 



Figure 8-13. Color Memory Map 
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HOW COLOR MEMORY IS 
INTERPRETED 



Black 


8 Orange 


1 White 


9 Brown 


2 Red 


10 Light Red 


3 Cyan 


11 Dark Gray 


4 Purple 


12 Medium Gray 


5 Green 


13 Light Green 


6 Blue 


14 Light Blue 


7 Yellow 


15 Light Gray 



Figure 8-14. Color Codes — 40 Columns 



CHARACTER MEMORY 

In standard character mode, the C128 receives character data from the CHARACTER 
ROM. The character ROM is stored in the range 53248 ($D000) through 57343 
($DFFF). Since the VIC chip is capable of accessing 16K at a time, the CI 28 needs a 
way to have the character ROM available in the 16K VIC range. In C128 mode, the 
character ROM is available in any VIC bank in CI 28 mode, based on the value of 



u 



The contents of the color RAM locations contains the color codes 0-15. Each color ^ 

memory location may have a different color code. The lower four bits (nybble) of 
COLOR RAM are significant. Figure 8-14 shows the COLOR RAM color codes: 






\ I 
I I 

u 
1 i 

u 

u 



Notice these color code values are one less than the color codes used by the ' { 

keyboard and BASIC. If you want to store a value directly into COLOR RAM, store the U 
values in the table above, not the color codes used by BASIC and the keyboard. For 

example: ^ 

POKE 55296,1 L 

colors the character in the HOME position white. From the monitor, place the value 1 in 
location $D800, and the same results occur. 

Remember, these color codes only control the color of the foreground character. 
The background color is controlled by background color register (53281). The pixels 
that make up the character image are enabled by bits in character memory. If the bit is i j 

enabled, the pixel in the foreground is turned on in the foreground color, and is ^ 

therefore controlled by color RAM. If the bits making up the character are turned off, 
they default to the color in background color register 0. The combination of on and off ( ( 

bits makes up the image of the character. The value of these bits determines whether the Li 

color data comes from color RAM or background color register 0. You'll learn more 
about character patterns in the next few paragraphs. , , 
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CHAREN. See the chapter set availability in the Character Memory section in the 
beginning of this chapter. 

In C64 mode the character ROM is available only in banks and 2. This is 
accomplished by having a ROM IMAGE of the character ROM (53248-57343) mapped 
into memory in place of RAM, in the range 4096-8191 ($1000-$1FFF) in video BANK 
0, and 36864-40959 ($9000-$9FFF) in video BANK 2. In banks 1 and 3, the character 
ROM is not available to the VIC chip. 

Notice that the range where the character ROM is actually stored (53248-57343) 
is also occupied by the I/O registers but not at the same time. When the VIC chip 
accesses the character ROM, the character ROM is switched into the currently selected 
video bank as a ROM image (in C64 mode only). When the character ROM is not 
needed, the I/O registers are available in the usual range. It is important to note the 
ROM image applies only to the character data as seen by the VIC chip. The RAM loca- 
tions where the ROM image maps in are still usable for programs and data. The locations 
where the VIC chip looks for the character data are relocatable. See the Character 
Memory section elsewhere in this chapter for information on moving character memory. 

HOW TO INTERPRET CHARACTER MEMORY 
IN STANDARD CHARACTER MODE 
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Typically, a complete character set contains 256 characters. The C128 contains two sets 
of characters, for a total of 2 times 256 or 512 characters. In 40-column (VIC) output, 
only one character set is available at a time. Upon power-up, the uppercase/graphics 
character set is available through the keyboard. To access the second character set, press 
the Commodore key ( O ) and shift key at the same time. The second character set is 
composed of the upper- and lowercase/graphics characters. 

In character ROM, each character requires eight bytes of storage to make up the 
character pattern. Since 256*8 is equal to 2048 bytes or 2K, and since there are two 
character sets, the C128 has a total of 4K of character ROM. Figure 8-15 shows where 
each character set is stored in the character ROM. 





ADDRESS 


VIC-II 












BLOCK 


DECIMAL 


HEX 


IMAGE 


CONTENTS 





53248 


DOOO-DIFF 


lOOO-llFF 


Upper case characters 




53760 


D200-D3FF 


1200-13FF 


Graphics characters 




54272 


D400-D5FF 


1400-15FF 


Reversed upper case characters 




54784 


D600-D7FF 


1600-17FF 


Reversed graphics characters 


1 


55296 


D800-D9FF 


1800-19FF 


Lower case characters 




55808 


DAOO-DBFF 


lAOO-lBFF 


Upper case & graphics characters 




56320 


DCOO-DDFF 


ICOO-IDFF 


Reversed lower case characters 




56832 


DEOO-DFFF 


lEOO-lFFF 


Reversed upper case & graphics 
characters 



Figure 8-15. Location of Character Sets in Character ROM 
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Note that there is really 8K of character ROM— 4K for C64 mode and 4K for 
C128 mode. The system automatically selects the appropriate character ROM for each 
mode of operation. 

The bit patterns stored in the character ROM have a direct relationship to the 
pixels on the screen, where the character is displayed. In memory, each character 
requires eight bytes of storage. On the screen, a character is made up of an 8 by 8 pixel 
matrix. Think of a character as eight rows of eight pixels each. Each row of pixels 
requires one byte of memory, so each pixel requires one bit. 

Since a character is an 8 by 8 pixel matrix, each character requires a total of 64 
bits or eight bytes. Within each byte, if a bit is equal to 1, the corresponding pixel in 
that character position is turned on. If a bit in a character ROM byte is equal to 0, the 
corresponding pixel within the character on that screen position is turned off. The 
combination of on and off pixels creates the image of the characters on the screen. 
Figure 8-16 demonstrates the correspondence between a character on the screen and the 
way it is represented in the character ROM. 
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Byte1 - 
Byte2-» 
Byte 3 - 
Byte 4 - 
Bytes- 
Byte 6 - 
Byte 7- 
Byte 8-* 
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1 


1 











0. 





















$D000 
$D001 
$D002 
$D003 
$D004 
$D005 
$D006 
$D007 



Character on 
the Screen 



Character as 

Represented 

in Character ROM 



Figure 8-16. Relationship of Screen Character to Character ROM. 



In Figure 8-16, the first eight bytes of character ROM, ($D000-$D007) are equal 
to 60,102,110,110,96,98,60 and 0. These decimal numbers are calculated from the 
binary value of the eight bytes that pertain to each row of pixels in the character. For 
each bit that is equal to one, raise two to the bit position (0-7). For example, the first 
byte of character ROM ($D000) is equal to 60, which is calculated by raising two to the 
following bit positions: 

22 + 2^ + 2^* + 2^ = 4 + 8 + 16 + 32 = 60 

The bits that are set (on) correspond to pixels that are enabled on the screen in the 
foreground color. Bits that are clear correspond to pixels that are disabled, which are 
displayed in the background color, according to background color register at location 
53281. 

The second byte (row of pixels) of the at-sign (@) character is equal to 102 
(decimal) and is obtained by the following: 
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2" + 2^ + 2^ + 2^ = 102 

The last byte of the at-sign character is equal to zero, since no bits are set. 
Therefore, each pixel on the screen is displayed in the background color. The values of 
i the binary digits on the right in Figure 8-16 are directly related to the image of the 

character as it appears on the screen on the left in Figure 8-16. 

ACCESSING CHARACTER ROM 
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CI 28 BASIC 

To access character ROM in C128 BASIC, type and run the following program: 

10 BANK 14 

20 FOR 1=53248 TO 53248+7 :PRINTPEEK( I ); :NEXT 

30 BANK 15 

Enter Bank 14, the only BASIC bank where the character ROM is accessible. 
Then print the PEEK value of the first eight bytes of the character ROM. When 
finished, return to Bank 15. 

MACHINE LANGUAGE 

To access character ROM in C128 Machine Language, type and run the following 
program: 



MONITOR 




PC 


SR AC XR YR SP 


; FBOOO 


00 00 00 00 F6 


. 01800 


A9 01 LDA #$01 


. 01802 


8D 00 FF STA SFFOO 


. 01805 


A2 00 LDX #$00 


. 01807 


BD 00 DO LDA $DOOO,X 


. 0180A 


9D 40 18 STA $1840, X 


. 0180D 


E8 INX 


. 0180E 


EO 07 CPX #$07 


. 01810 


DO F5 BNE $1807 


. 01812 


A9 00 LDA #$00 


. 01814 


8D 00 FF STA SFFOO 


. 01817 


60 RTS 



10 SYS 6144 

20 FOR 1=6208 TO 6208 +7 : PRINTPEEK (I ) ; :NEXT 



These machine language and BASIC routines accomplish the same task as the preceding 
four-line BASIC program. The first two machine language instructions switch in the 
character ROM, and switch out I/O. The next six instructions transfer the first eight 
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bytes of character ROM into locations 6208 ($1840) through 6215 ($1847). The last 
three instructions switch out the character ROM, replace it with the I/O registers and 
return from the machine language subroutine to BASIC. 

The BASIC routine activates the machine language subroutine, then prints the 
values that were temporarily stored in 6208 through 6215. See Chapter 6, How to 
Enter Machine Language Programs, for details on how to input machine language 
instructions on the CI 28. 

C64 BASIC 

To access character ROM in C64 BASIC, enter and run the following program: 



40 POKE 56334, PEEK(56334)AND 254 

50 POKE 1,PEEK(1) AND 251 

80 FOR 1=0 TO 7: POKE 6144+1, PEEK( 53248+1 ) :NEXT 

90 POKE 1,PEEK{1) OR 4 

105 POKE 56334, PEEK(56334) OR 1 

130 FOR 1=6144 TO 6144+7 :PRINTPEEK(I ); :NEXT 



PROGRAMMABLE CHARACTERS 
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Line 40 turns off the interrupt timer. Line 50 switches out I/O and replaces it with 
character ROM. Line 80 transfers the first eight bytes of character ROM (53248-53255) 
to 6144-6151. Line 90 switches out character ROM, and replaces it with the I/O 
registers. Line 105 turns on the interrupt timer. Line 130 prints the first eight character 
ROM values that were temporarily stored in 6144 through 6151. 

You may need to transfer parts of the character ROM data into RAM if you are j | 

creating your own character set, and you want the remainder to be from the CI 28 '-' 

character set. This is covered in more detail later in the chapter. These methods of 
looking at the character ROM demonstrate how the character ROM is accessed, what the 1 ! 

patterns of the characters look like and why you would want to access the character Li 

ROM. 

The next section explains how to program your own custom characters in CI 28 i i 

mode. J 



\ j 

u 



The Commodore 128 has a feature that allows you to redefine the character set into 
custom characters of your own. In most cases, you'll want to redefine only a few ) | 

characters at most, while obtaining the rest of the character set from the Commodore M 

128 character ROM. 

With programmable characters, you tell the CI 28 to get character information 
from RAM. Usually, characters are taken from the character ROM. If you only want 
certain characters, you can choose the ones you want, copy the character patterns into 
RAM and leave the rest in ROM. You cannot write to the character data in ROM; 
however, the character data placed in RAM can be redefined. 

The first step in programming your own characters is to define the image. In the 



U 



U 



U 



THE POWER BEHIND COMMODORE 128 GRAPHICS 231 



n 

r 

i 

n 
n 

i 

n 
n 

n 
n 



n 



Standard Character Mode section, you saw how a character on the screen is stored in the 
character ROM. Each character requires eight bytes of storage. Each byte corresponds to 
a row of pixels on the visible screen within the 8 by 8 character matrix; therefore, eight 
rows of pixels make up one character. 

This section shows how to customize an uppercase cursive (script) character set 
for the letters A through H. Figure 8-17 shows the design for the uppercase cursive 
letter A. The grid in the figure demonstrates how the character appears on the screen 
within the 8 by 8 pixel matrix. Each row of the grid determines which bits are on within 
the character bit pattern, and, hence, which corresponding pixels are enabled on the 
screen. The eight-bit binary strings to the right of the grid are the bit patterns as stored 
in RAM. The numbers to the right of the binary strings are the decimal equivalents of 
the binary bit patterns. This decimal value is the data you POKE into RAM in order to 
display the character. 



= 00001110 = 14 
= 00010001 = 17 
= 00100000 = 32 
= 01000010 = 66 
= 10000010 = 130 
= 10000100 = 132 
= 10001010 = 138 
= 01110001 = 123 



Figure 8-17. Design for Cursive letter "A" 

The following program creates and displays the upper-case cursive characters A 
through H. Enter it into the computer and RUN it. You'll see the letters A through H 
change from uppercase block letters to uppercase cursive letters. When you press the 
newly defined lettered keys, they are displayed in cursive form. 

Line 10 selects the uppercase character set, the set being redefined. Line 20 
protects the character set from being overwritten by the BASIC program and prepares a 
location in RAM in which to place your character set. The end of user BASIC text and 
the top of string storage is moved from 65280 to 12288 (decimal), which substantially 
cuts down the size of BASIC programming space. The character set will be placed 
beginning at location 12288, but it does not have to be located there. The character set 
does have to be within the first 16K of memory unless another bank is selected. The 
VIC chip can only access I6K at a time so each video bank consists of 16K of memory. 
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10 PRINT CHR$(142) :REM SELECT UPPER CASE 

20 POKE54,48:POKE58,48:CLR:REM PROTECT CHAR SET 

30 BANK 14 :REM SWITCH TO BANK 14 FOR CHARACTER ROM 

40 F0RI=1 TO 511:POKEI+12288,PEEK(I+53248) :NEXT!REM ROM TO RAM TRANSFER 

50 BANK 15: REM SWITCH TO DEFAULT BANK 

60 POKE 2604,(PEEK(2604) AND 240)+12:REM START CHAR BASE AT 12288 

70 FORJ=12288T012288+71 rREM PLACE CHARACTER DATA IN RAM 

80 READ A 

90 POKE J, A 

100 NEXT J 

110 SCNCLR 

120 DATA 0,0,0,0,0,0,0,0:REM @ 

130 DATA 14,17,32,66,130,132,138,123:REM A 

140 DATA 124,66,66,124,66,81,225,126:REM B 

150 DATA 62,67,130,128,128,128,131,126:REM C 

160 DATA 125,98,125,65,65,193,161,254!REM D 

170 DATA 225,66,64,56,120,65,66,124:REM E 

180 DATA 127,129,2,4,14,228,68,56:REM F 

190 DATA 193,163,253,33,249,65,99,190:REM G 

200 DATA 227,165,36,36,126,36,37,231:REM H 



u 
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You can leave yourself more BASIC text area, but to do this you must enter a video 

bank higher than zero. This sample program operates in Bank 0. If you place your i 

character set in a higher video bank, remember to add an offset of 16384 ($4000) to the 

start of RAM character memory for each bank above video Bank 0. 

The CLR in line 20 clears out memory starting at 12288 because, prior to the 
placement of the character set there, the memory locations are filled with random bytes. j 

The random bytes must be cleared before new character information can be stored. U 

. Line 30 selects BANK configuration 14. This configuration makes the character 
ROM visible with a PEEK command or within the machine language monitor, and 
temporarily switches out the I/O registers. Both the I/O functions and the 4K character 
ROM share the same locations ($D000-$DFFF). Depending on whether bit in the 
configuration register (location $FF00) is on or off, the CI 28 addresses the I/O registers 
or the character ROM. Normally the C128 powers up with bit 1 turned off; therefore, | 

the I/O registers in locations $D000-$DFFF are addressed. The BANK command in line ^ 

30 sets bit in location $FF00; therefore, the character ROM in locations 53248-57343 
($D000-$DFFF) is addressed. The character ROM is accessed in order to make the I 

transfer of characters to RAM. _j 

Line 40 makes the actual transfer from ROM to RAM. Since the character ROM is 
accessed in line 30, it now begins at location 53248. The first 512 bytes (the uppercase 
character set) from the character ROM are POKEd into the 512 bytes of RAM beginning 
at location 12288 and ending at 12800. At this point the character set is ready to be 
redefined to custom characters. 

Line 50 switches the I/O registers back in, meaning the character ROM is no 
longer available. 

Line 60 specifies the start of the character set base at location 12288. The character 
set base can be stored in locations other than 12288. (See the Character Memory section 
earlier in this chapter for more information on moving character memory.) Location 
2604 is the intermediate memory location that the interrupt-driven CI 28 screen editor 
uses to point to screen and character memory in character mode. You must use this 
indirect location to change the value of the actual register that points to the screen and 
character memory 53272. If you try to POKE directly to location 53272, the interrupt will 
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change the value back to the original one within a sixtieth of a second. (You can, how- 
ever, disable the interrupt-driven screen editor. See the Shadow Register section for details.) 
n The value (AND 240) or 12 is placed in address 2604 to tell the CI 28 to point to 

■ ' character memory in RAM, starting at address 12288. If the value (AND 240) or 8 is 

placed into 2604, the character set will begin at 8192 and your BASIC program must be 
n less than 6K, but the complete 4K of characters can be redefined. If the value (AND 240) 

I i or 14 is placed into that location, the character set starts at 14336. Your BASIC program 

then must be less than 2K, since the programmable character set must reside within a 

nl single 16K block, but the BASIC program that creates the characters can be almost 14K. 

I If a number other than 12 is POKED into 2604, other program lines must be modified. 

Lines 70 through 100 start a loop at the beginning of the character base (12288), 
read the values from the data statements which define the new characters (lines 120 and 
n 200), and POKE them (line 90) into the locations allocated for the character set base, 

I 1 starting at location 12288. The value 12288 + 71 in line 70 sets aside seventy-two 

storage locations for the data values in lines 120 through 200 for storage in locations 
n 12288 through 12359. When more data statements are added, the value (12288-1-71) 

I must be increased to 12288 plus the number of data values in the data statements minus 

1. For example, if more characters were defined and there were twenty data statements 
with eight values in each, then line 70 would read: 

"I 70 FOR J = 12288 TO 12288 + (160-1) 



MULTI-COLOR CHARACTER MODE 

Standard character mode displays text in two colors: the foreground color of the 
character as determined by COLOR RAM, and the background color as determined by 
background color register at location 53281 ($D021). 

Multi-color character mode gives you the ability to display characters in four colors 
within an 8 by 8 character matrix. This substantially increases the freedom of using color. 
However, the horizontal resolution is only half the resolution of standard character mode 
(160*200), since multi-color mode bits and screen pixels are grouped in pairs. This means 
that the color definition and pixel density is twice as wide as standard character mode. The 
tradeoff in horizontal resolution is compensated for by the increased freedom of using color. 

HOW TO ENTER MULTI-COLOR MODE 

Location 53270 and its shadow register ($00D8) determine whether the CI 28 is output- 
ting standard or multi-color characters on the screen. Bit 4 of 53270 and bit 7 of 216 
($00D8) control multi-color mode for character and bit map modes. If bit 4 of 53270 
(and bit 7 of 216) is equal to 1, multi-color mode is enabled. Otherwise, standard mode 
is enabled. Most of the new 7.0 BASIC graphics commands have provisions for multi- 
color mode. However, if you want to enter multi-color mode with a POKE command, type: 

10 POKE 216,255: REM Disable IRQ Editor 

20 POKE 53270, PEEK (53270) or 16: REM Select MCM 

This enters multi-color mode, either for character mode or bit map mode. 
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SCREEN LOCATION 

The screen location in multi-color character mode defaults to 1024 ($0400) through 2023 
($07E7), the same as standard character mode. The screen memory locations can be 
relocated. See the Screen Memory section for details. 

HOW SCREEN DATA IS INTERPRETED 

In multi-color character mode, the screen data from screen memory is interpreted as 
screen codes the same way as in standard character mode. The screen codes are listed in 
Appendix D. See the screen data interpretation in the standard character memory 
section. The only difference between standard character mode and multi-color character 
mode is the way color is assigned to the characters on the screen. 

CHARACTER MEMORY LOCATION 

The character memory in multi-color character mode, as in standard character mode, is 
taken from between 53248 ($D000) and 57343 ($DFF) when I/O is switched out. See 
standard character mode for more detailed information on character memory. 

HOW CHARACTER MEMORY IS INTERPRETED 
IN MULTI-COLOR CHARACTER MODE 

Character memory is interpreted virtually the same way in multi-color and in 
standard character modes, except for one difference: In standard character mode, if 
a bit in the character definition image is on, the pixel corresponding to that bit 
is colored in the foreground color as specified by color RAM. If a bit in the character 
image in the character ROM is equal to zero, the corresponding pixel on the screen is 
colored in the background color, as specified by background color register (loca- 
tion 53281). 

In multi-color character mode, color assignments to the pixels that make up the 
character on the screen are not in a direct one-to-one relationship to the bits in the 
character ROM data patterns. Instead, the bits that make up a character are grouped in 
pairs, as shown in figures 8-18, 8-19 and 8-20. 
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Figure 8-18. "At" Sign (@) Character as It Appears on the Screen 
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Figure 8-19. Bit Patterns of the "At" Sign (@) Character as They Appear in 
Character ROM 
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Figure 8-20. Bit Patterns of the "At" Sign (@) Character as They Are Grouped 
in Pairs in Multi-Color Character Mode 

The bits are grouped in pairs, since the horizontal resolution is only half as wide in 
multi-color mode. The bit pair determines the color assignments for the pixels within the 
character on the screen. The following section describes how the colors are assigned in 
multi-color character mode. 



COLOR DATA 

The color of the pixels in a multi-color character originate from four sources, depending 
on the bit pairs. Since the bit pairs have four color possibilities, two bits are needed to 
represent four values: 00, 01, 10 and 11! In Figure 8-21, the value of the four bit pair 
combinations determines the color assignments for the pixels in a multi-color character. 



BIT PAIR 

00 
01 
10 
11 


COLOR REGISTER 

Background #0 color (screen color) 
Background #1 color 
Background #2 color 
Color specified by the 
lower 3 bits in color memory 


LOCATION 

53281 ($D021) 

53282 ($D022) 

53283 ($D023) 
color RAM 



Figure 8-21. Truth Table for Color Data 
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If the bit pair equals 00 (binary), the color of those two pixels corresponding to the L 

bit pair are colored by background color register (location 53281 ($D021)). If the bit 
pair equals 01 (binary), the pixels are colored by background color register 1 (location i 

53282 ($D022)). If the bit pair equals 10 (binary), color for those two pixels within the I 

character are colored from background color register 2 (location 53283 ($D023)). 
Finally, if the bit pair from the character pattern equals 1 1 (binary), those two pixels are 
colored from the color specified in the lower three bits (2, 1, 0) of color RAM. Color 
RAM is located between 55296 ($D800) and 56295 ($DBE7). 1- 

When multi-color character mode is selected, you can still display standard 
characters on some screen locations, and display others in multi-color mode. Bit 3 of 
each color RAM location determines whether the character is displayed in standard or 
multi-color mode. If bit 3 in color RAM is set (1), characters are displayed in 
multi-color mode. If bit 3 is clear (0), characters are displayed in standard character mode. 
This means that in order to display characters in multi-color mode, you must fill color 
RAM with a color code greater than 7. The colors greater than 7 (the ones that are 
displayed in multi-color mode) are shown in Figure 8-22. 



COLOR CODE 


COLOR 
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Orange 
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Brown 


10 


Light Red 


11 


Dark Gray 


12 


Medium Gray 


13 


Light Green 


14 


Light Blue 


15 


Light Gray 



Figure 8-22. Color Codes 



REM BKGND = BLACK 
REM MULTCLR 1 = WHITE 
REM MULTCLR 2 = RED 



10 COLOR 0,1 
20 COLOR 2,1 

30 COLOR 3,2 

31 FOR I=1T025 

32 PRINT "ABCDEFGHIJKLMN0PQRSTUVWXY2" 

33 NEXT 

35 FOR 1=55296+512 TO 55296+1023 :P0KE I,7:NEXT:REM PLACE YELLOW IN COLOR RAM 

37 POKE 216, 255:REM DISABLE SCREEN EDITOR 

40 POKE 53270, PEEK(53270) OR 16:REM SET MULTICOLOR BIT 

50 FOR I=1T025 

60 PRINT "ABCDEFGHIJKLMNOPQRSTUVWXYZ" 

70 NEXT 

85 FOR 1=55296 TO 55296+1023:POKE I, 14 :NEXT:REM FILL COLOR RAM WITH BLUE 

90 GRAPHIC 0:REM RETURN TO STANDARD COLOR 

Lines 10, 20 and 30 place the color codes for black, white and red into background 
color registers 0, 1 and 2, respectively. Lines 31 through 33 print the letters of the 
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Remember, the multi-color bit (bit 3) must be set to display multi-color characters. 
The following program illustrates multi-color character mode. 
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alphabet on the screen twenty-five times. Line 35 fills the last 512 bytes of color RAM 
with yellow. Line 37 disables the IRQ VIC screen editor. Line 40 enables multi-color 
mode. At this point, all the screen locations corresponding to the color RAM locations 
which have a color code greater than or equal to 8 are displayed in multi-color mode. 
Since the yellow color code is 7, all the color RAM locations having this code are 
placed in standard character mode. The default color for color RAM is code 13 (light 
green) for C128 mode, and code 14 (light blue) for C64 mode. Line 85 fills color RAM 
with the light blue color code. The multi-color characters displayed on the screen are 
red, white and blue on a black background. 



EXTENDED BACKGROUND COLOR MODE 



The third type of character display mode, extended background color mode, allows you 

nto display three colors at a time on the text screen. For example, you have the character 
color, the background color of the screen, and an additional background color within 
each 8 by 8 character matrix. This means you can display a white character with a green 
background in the 8 by 8 character matrix, on a black screen background. This mode 
"1 offers the use of an additional color in an 8 by 8 character matrix, without any loss in 

I screen resolution. 

There is one sacrifice, however. In extended background color mode, only the 

p first sixty-four characters of the screen code character set are available. The reason for 

this is that bits 6 and 7 determine which color will be selected for the background within 

the 8 by 8 pixel character matrix. This only leaves five bits for the computer to interpret 

which character is currently on the screen. The highest number you can represent with 

^ five bits is 63. This means only the screen code values between and 63 are available 

! for display on the screen within extended background color mode. 



HOW TO ENTER EXTENDED 
BACKGROUND COLOR MODE 

Enabling bit 6 of location 53265 selects extended background color mode. Use this 
POKE in BASIC: 

POKE 53265, PEEK(53265) OR 64 

To turn it off, use this POKE: 

POKE 53265, PEEK(53265) AND 191 

SCREEN LOCATION 

The screen location in extended background color mode is the same as the standard 
character and multi-color character modes, 1024 ($0400) through 2023 ($07E7). This 
screen range can be relocated. See the SCREEN MEMORY section for details. 
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HOW TO INTERPRET SCREEN DATA 

The data in screen memory is interpreted as screen codes, which are actually the indexes 
into the character ROM. Instead of representing the data as ASCII characters, the screen 
codes represent the index into the character ROM which provide the ASCII codes. The 
first character in character ROM is the at sign (@); therefore the first screen code, 0, is the 
code for the at sign. 

Remember, since extended background color mode only uses five bits to deter- 
mine the screen code value, only the first 64 screen code characters (0-63) are available. 
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COLOR DATA 

The color assignments for the three colors on the screen stem from three sources. Just as 
in standard character mode, the foreground color is assigned by COLOR RAM, in the 
range 55296 ($D800) through 563295 ($DFE7). As described in the standard character 
mode section, each color RAM location has a direct one-to-one correspondence with the 
screen memory locations. See the Standard Character Mode section for screen and color 
memory maps and an explanation of how the two sections of memory correspond to one 
another. 

The screen background color is assigned by background color register zero (location 
53281 ($D021)). This is the color of the entire screen, on which the foreground and an 
additional 8 by 8 character matrix background is placed. 

The additional 8 by 8 character matrix background colors are determined by the 
value of bits 6 and 7 of the screen code character value. Depending on the value of these 
bits, the extended background color (the color within the 8 by 8 character matrix for 
each character), comes from one of the four background color registers. Since there are 
four choices for the extended background color, the computer needs two bits to 
represent the four color choices. Figure 8-23 shows the four-bit combinations and the 
corresponding background color registers associated with them. 



CHARACTER CODE 



BACKGROUND COLOR 
REGISTER 



RANGE 



BIT 7 



BIT 6 



NUMBER 



ADDRESS 



0-63 





64-127 





28-191 


1 


92-255 


1 



53281 ($D021) 

53282 ($D022) 

53283 ($D023) 

53284 ($D024) 



Figure 8-23. Extended Background Color Registers 






For example, POKE the screen code for the letter A (1) into screen location 1024. 
Now POKE the screen value 65 into screen location 1025. You might expect the 
character to be a reverse A, the second character of the second screen code character set. 
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However, in this mode, you can only represent the first sixty-four characters, since you 
only have five bits to represent screen characters. By trying to represent the screen code 
65, bit 6 is enabled, which tells the computer to select the background color register 1 
(location 53282 ($D022)), and display the same character, but with the extended 
background color specified by background color register 1 . 

Here's a program that illustrates how extended background color mode operates: 



5 SCNCLR 

10 COLOR 0,1 :REM BKGRD=BLACK 

20 COLOR 2,1 :REM MULTICOLOR 1 

30 COLOR 3,2 :REM MULTICOLOR 2 

40 POKE 53284, 3: REM BACKGRD COLOR 3 

45 POKE 53265, PEEK(53265) OR 64:REM SET EXTENDED BKGRND BIT 

50 FOR 1=1024 TO 1256:POKE I,I-1023:NEXT 

60 PRINT: PRINT: PRINT: PRINT 



In the program, line 5 clears the screen. Lines 10 through 40 assign colors to the 
four background color registers: black, white, red and cyan, respectively. Line 45 
enables extended background color mode. Line 50 POKEs 232 characters into screen 
memory. Each time sixty-four characters are stored into the screen memory, the same 
set of sixty-four characters is POKEd into the next sixty-four screen locations. However, 
the next extended background color is displayed. First, the sixty-four characters are 
displayed with a black extended background, then a white extended background, then 
red, then cyan. 

CHARACTER DATA 

Character data is interpreted the same way as in standard character mode, except only 
the first 64 characters of the screen character set are available. The character data is also 
located in the same range as in standard character mode. See standard character mode 
for more information on character data. 



STANDARD BIT MAP MODE 



Standard Bit Map Mode, also referred to as high-resolution mode, offers the ability to 
display detailed graphic images in two colors. The resolution of bit map mode is 
320 by 200 pixels. In this mode, the CI 28 no longer operates in terms of characters, 
which are 8 by 8 pixel images stored in those complete units at a time. Bit map mode 
allows you to address single pixels at a time, therefore exercising a substantial amount 
of control over the detail of images on your screen. The smallest unit addressed in the 
character display modes is an 8 by 8 pixel character. Standard bit map mode allows you 
to address every individual pixel of the possible 64000 pixels that make up an entire 
high-resolution screen image. Figure 8-24 shows how that bit-map coordinate plane is 
set up. 
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Figure 8-24. Bit Map Screen Coordinates 



HOW TO ENTER STANDARD BIT MAP MODE 

To enter standard bit map mode, set bit 5 of location 216 ($00D8) (the shadow 
register of location 53265 ($D011)). When you issue the GRAPHIC 1,1 command 
in C128 BASIC, bit map mode is enabled and the bit map screen is cleared. 

You can also use a POKE command as follows, but you should use the highest- 
level commands wherever possible: 

POKE 216, PEEK (216) OR 32 

This command turns on bit 5 of the GRAPHM register, which is the interface between 
the VIC chip and the interrupt-driven CI 28 screen editor. This indirectly turns on bit 5 
in location 53265 and enters bit map mode. 

You can disable the interrupt-driven screen editor and select bit map mode directly 
with these commands: 

POKE 216, 255 

POKE 53265, PEEK (53265) OR 32 

In C128 mode machine language, use this program sequence: 

LDA $00D8 
ORA #$20 
STA $00D8 

In C64 mode machine language, try this: 

LDA $D011 

ORA #$20 
STA $D011 

THE VIDEO MATRIX 

(SCREEN MEMORY) LOCATION 

The default location of the CI 28 video matrix (i.e., the bit map screen memory) is 7168 
($1C00) through 8167 ($1FE7). 

The default location of the C64 video matrix is 1024 ($0400) through 2023 
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' ' ($07E7). The video matrix can be moved, however. See the Screen Memory section 

elsewhere in this chapter for information on relocating the video matrix. 

n HOW THE VIDEO MATRIX 

IS INTERPRETED 

In bit map mode, the video matrix (bit map screen memory) is interpreted differently 
than it is in the character display modes. In the character display modes, the screen 
memory data is interpreted as screen codes corresponding to the characters in character 

"1 ROM. However, in bit map mode, the video matrix data is interpreted as the supplier of 

i color information for the bit map. The upper four bits (nybble) supply the color 

information for the bit map foreground, and the lower nybble supplies the color code for 

,— ( the bit map background. 

I The next section explains how pixels on the bit map screen are assigned to either 

the foreground color or the background color. 

n BIT MAP DATA 

In bit map mode, the character data, referred to as the bit map, is also interpreted 
P differently than in the character display modes. The character data is not taken from 

j j character ROM at all. Instead, it is taken from an 8K section of RAM memory, known 

as the bit map. 

The standard high-resolution screen is composed of 200 rows of 320 pixels, so 
that the entire screen is composed of 64,000 pixels. In bit map mode, one bit in memory 
is dedicated to an individual pixel on the screen. Therefore 64000 pixels require 64000 
bits (or 8000 bytes) of memory to store the entire bit mapped image. 

If a bit in memory in the 8000 byte bit map is set, the corresponding pixel on 
the screen is enabled, and becomes the color of the foreground as specified in the upper 
four bits of the video matrix. If a bit in the bit map is equal to zero, the corresponding 
pixel on the screen becomes the color of the background, as specified in the lower four 
bits of the video matrix. The combination of on and off bits in the bit map and the 
corresponding pixels on the screen define the highly detailed image on the video screen. 

The bit map default location in memory ranges from 8192 ($2000) through 16191 
($3F3F). This requires 8000 bytes or just under 8K of memory. The spare bytes are used 
for other purposes. Location 53272 determines the location of the video matrix and bit 
map in memory. Since the screen editor is running on the IRQ, location 2605 ($0A2D) 
is an indirect address you must use to place a value in location 53272 ($D018). The 
upper four bits of 53272 determine where the video matrix begins and the lower four 
bits determine where the bit map begins. In bit map mode, only bit 3 is significant, so 
the bit map is either placed starting at location or location 8192 ($2000) in each video 
bank. 

If you change to a higher bank number, remember to add an offset of $4000 to the 
start of die bit map and the video matrix for each bank number above 0. 

The video matrix is relocatable. See the Screen Memory section in the beginning 
of the chapter for details on how to move the video matrix. 
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The bit map tells the computer which pixels in the foreground to enable on the 
screen. Like a road map, it spells out exactly which pixels to turn on (in the foreground) 
and off (in the background color) in order to display a picture on the screen. For 
example, if the bit map started at location 8192 (the CI 28 BASIC default) the first 
byte of the bit map corresponds to the bit map pixel coordinates 0,0 through 0,7. The 
second byte of the bit map, location 8193, corresponds to coordinates 1,0 through 1,7 
and so on. See Figure 8-25 to see how the bit map data in locations 8192-16191 
correspond to the pixels on the visual screen: 



X Coordinate 



■\ 319,0 



Y Coordinate 
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Figure 8-25. Relationship of Bit Map Data to Screen Pixels 



Now you know how bit map mode operates internally within your CI 28. However, 
you need an easy way to turn on and off pixels in the bit map in order to display 
graphics on the screen. The new, high level BASIC 7.0 commands such as DRAW, 
CIRCLE, BOX and PAINT allow you to control the turning on and off of bits and their 
corresponding screen pixels. The use of the X and Y coordinates on the bit map 
coordinate plane easily orient you to displaying graphics. You can display high- 
resolution graphics in other ways, outside of the BASIC 7.0 graphics commands. 
This includes using commercial software packages that employ graphics tablets or 
joysticks to draw on the screen, writing your own draw routines using a joystick or 
paddle, or physically entering data into the bit map (which is painfully tedious and not 
recommended). 
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Another way to display graphics, which involves manipulating bits in the bit map, 
is through mathematical equations, using geometry. Several books are available which 
offer geometrical equations on how to draw three-dimensional objects and to move them. 
Refer to the Suggestions for Further Reading the back of the book for sources on graphics. 

COLOR RAM 

In standard bit map mode, color RAM is not used since the color information for the bit 
map is taken from the upper and lower nybble of screen RAM. Color RAM is used, 
however, in multi-color bit map mode. 



MULTi-COLOR BIT MAP MODE 

Multi-color bit map mode is a combination of standard bit map mode and multi-color 
character mode. Multi-color bit map mode allows the display of four colors within an 8 
by 8 pixel bit map area. Like multi-color character mode, the horizontal resolution is 
only half of the standard bit map mode, though the tradeoff in resolution is compensated 
for by the use of two additional colors within an 8 by 8 pixel, bit mapped area. 

HOW TO ENTER MULTI-COLOR 
BIT MAP MODE 

To enter multi-color bit map mode from C128 BASIC, issue the following command: 

GRAPHIC 3 

You can enter this mode with a POKE command as well. But make use of the 
highest level commands available for the easiest programming: 

POKE 216, PEEK (216) OR 160 

This POKEs the value 160 and turns on the multi-color mode bit 7 (value 128) and 
the bit map mode bit 5 (value 32) in the GRAPHM register which interfaces to the CI 28 
interrupt driven screen editor. This indirectly turns on, respectively, bit 4 (multi-color 
mode) of location 53270 ($D016), and bit 5 (bit map mode) of location 53265 ($D011). 

Bit 5 of location 53265 determines whether the C128 is in bit map mode or 
character mode. If bit 5 is equal to 1, bit map mode is enabled. Bit 4 of location 53270 
determines whether the CI 28 is in standard or multi-color mode. If bit 4 is set, the 
CI 28 operates in multi-color mode, regardless of whether it is in character or bit map 
mode. 

In C64 mode, you can store a value directly to these registers. But in C128 mode, 
the GRAPHM intermediate register must be used as a gateway to these actual registers. 
Again, this is because the C128 screen editor is interrupt driven, enabling the split- 
screen modes for text and simultaneous bit map displays. Since the screen editor is 
interrupt driven, an indirect register is used to restore the values that you need to use for 
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Specific VIC registers. GRAPHM is one such register; therefore, every sixtieth of a 
second, the value in the GRAPHM register is loaded into the appropriate VIC registers. 



VIDEO MATRIX LOCATIONS 

The video matrix defaults to locations 7168 ($1C00) through 8167 ($1FE7) in C128 
mode. 

In C64 mode, the video matrix defaults to locations 1024 ($0400) through 2023 
($07E7). This is relocatable. See the Screen Memory section earlier in this chapter. 

HOW TO INTERPRET THE VIDEO MATRIX 

The contents of the video matrix are interpreted the same way as in standard bit map 
mode. The upper nybble is the color code for the foreground color; the lower nybble is 
the color code for the background color of the bit map. 

ADDITIONAL COLOR DATA 



U 
U 

u 

u 



MACHINE LANGUAGE 

To select multi-color bit map mode in CI 28 machine language, perform the following 
instructions: 

LDA $A0; enables bits 4 and 5 of GRAPHM, the shadow location 
STA $00D8 

In C64 machine language, enter: 

LDA $D011 

ORA #$20; select Bit map mode 
STA $D011 
LDA $D016 

ORA #$10; select multi-color mode j [ 

STA $D016 IJ 

In both cases, you must clear the screen, color RAM and the bit map in your own 
program. j ( 



Q 



u 



U 



The upper and lower nybbles of screen memory supply the multi-color bit map screen j j 

with two of the color sources. This mode offers two additional colors — background [J 

color register (location 53281) and the lower nybble of color RAM. 

As in multi-color character mode, the bit patterns of the bytes in the bit map r 

determine the color assignments for the pixels on the screen. The bits are similarly 
grouped in pairs, within 8-bit bytes, so there are 4-bit pairs in each byte. Bits and 1 , 2 
and 3, 4 and 5, and 6 and 7 are grouped in pairs respectively. Depending on the values 
of the bit pairs, the corresponding pixels in the bit map are assigned colors from the 
sources in Figure 8-26. 



u 



n 



I I 



I i 



n 
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BITS COLOR INFORMATION COMES FROM 

00 Background color #0 (screen color) 

01 Upper four bits of video matrix 

10 Lower four bits of video matrix 

11 Color RAM 

Figure 8-26. Multi-Color Bit Map Pixel Color Assignments 



n THE BIT MAP 

Bit patterns determine how color is assigned to the multi-color bit map screen. If the bit 
p pair is equal to 00 (binary), color is taken from background color register (location 

I j 53281). If the bit pair is equal to 01 (binary), the color assigned to these two pixels 

comes from the upper nybble of video matrix. If the bit pair in the bit map is equal to 
^^ 10 (binary), then the color assigned to those two pixels comes from the lower nybble of 

j I video matrix. Finally, if the bit pair in the bit map is equal to 11 (binary), the color is 

' ' taken from the lower four bits of color RAM. Unlike multi-color character mode, the 

screen is either all standard bit map, or all multi-color bit map, unless you develop a 
<p sophisticated interrupt-driven application program that handles the two separate bit 

j I maps. 

n COLOR RAM 



In multi-color bit map mode, color RAM is used if the bit pair from the bit map equals 
11 (binary). Each color RAM location may have one of sixteen color codes, which 
means that one 8 by 8 bit map area can have black, red, white and blue colors, 
respectively, for the background color register 0, the upper nybble, the lower nybble, and 
the color RAM. The 8 by 8 multi-color bit map area next to it can have black, red, white 
and green colors, since each color RAM location is independent of any other. The other 
three color sources usually remain constant throughout a bit map screen, though you can 
change the upper and lower nybbles of the video matrix. The background color register 
is almost always the same throughout a bit map screen. 

The CI 28 has powerful and varied graphics display capabilities. Certain applica- 
tions call for one type of display over another. Experiment with them all and see which 
one meets your needs best. Figures 8-28 through 8-32 provide a graphics programming 
summary that should be helpful in understanding graphics on the CI 28. 



SPLIT-SCREEN MODES 



The Commodore 128 has a split-screen feature that allows you to display the top portion 
of the screen in bit map mode and the bottom portion in character mode. This allows you to 
enter a BASIC graphics program and RUN it while the BASIC program listing is 
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present and the bit map innage is displayed, which saves time switching back and forth 
between bit map and character modes. 

Before, you would have had to enter the graphics program (in machine language), 
RUN it and switch back to the text screen to make a change. Now you can display the 
graphic image and have your text screen available to you all at the same time. You can 
alter the program while your bit map image is still on the screen, RUN it and see the 
immediate results without losing the text screen. 

Without the Commodore 128's split-screen capabilities, you would have to pro- 
gram a split screen yourself. This involves raster interrupts which utilize either two 
screen memories in two different video banks, or a fairly choppy single-screen memory, 
usually with a visible raster line. With the C128 split-screen mode, all you have to do to 
enter a split-screen mode is to issue the GRAPHIC command in BASIC. For example, 
the command: 

GRAPfflC 2,1 

sets up a standard bit map screen on top and a text screen on the bottom. Similarly, the 
command: 

GRAPHIC 4,1 

constructs a multi-color bit map screen on the top portion of the screen and a text screen 
on the bottom portion. The "1" in these commands clears the bit map screen. To leave 
the bit map screen intact, once you have already displayed an image, replace the "1" 
with a zero (0). 

The GRAPHIC command has an additional parameter that allows you to define 
where the split occurs. The split-screen starting location is defined in terms of a 
character row, as if the C128 were in a character display mode. For example, 

GRAPHIC 4,1,15 

selects a split screen with multi-color bit map mode on top of the screen and the text 
screen on the bottom, starting at character row 15. If the start of the split screen is not 
defined, the C128 defaults the start to line 19. 

HOW SPLIT-SCREEN MODES ARE 
ORGANIZED IN MEMORY 

SCREEN LOCATIONS 

The split-screen modes, both multi-color and standard, use two independent screen 
memories. The bit map video matrix is taken from the address range 7168 ($1C00) 
through 8191 ($1FFF), just as in standard and multi-color bit map modes. The text 
portion of the screen takes its screen memory from default character mode screen 
locations 1024 ($0400) through 2023 ($07E7), just as in standard and multi-color 
character mode. The hidden portions of the screen, the bottom portion of the bit map 
screen and the upper portion of the text screen, still store data, but it is invisible 
since the other screen memory has overlaid it. 







u 





u 
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I INTERPRETING SCREEN DATA 

The text portion of the split screen is interpreted according to the standard character mode 
p section. The bit map portion, whether standard or multi-color, is interpreted according to the 

I t description in the bit map mode section. Consult the Standard Character Mode, Standard Bit Map 

Mode and Multi-color Bit Map Mode sections for information on how screen data is interpreted. 

n CHARACTER MEMORY LOCATIONS 

' ^ The split-screen modes also take character data from two independent parts of memory. 

The bit map data, referred to simply as the bit map, is taken from the default range 8192 
p ($2000) through 16191 ($3FE7) for both the multi-color and standard bit map mode 

j j portions of the screen. 

The character memory for the text portion of the split screen is derived from the 

character ROM. The actual character ROM occupies the memory locations 53248 
n ($D000) through 57343 ($DFFF) overlaying the I/O registers. The I/O registers must be 

' I switched out to view the actual character ROM, in bank configuration 14, for example. 

For information on how character data is interpreted in standard character, stan- 
r^ dard bit map and multi-color bit map modes, see the sections describing these modes. 

I [ See also the Color RAM Banking section. 

p COLOR DATA 

' I Each of the standard bit map, multi-color bit map and standard character modes interpret 

color differently. See each section for detailed information on color assignments. 

n 

I I MACHINE LANGUAGE 

In machine language, you must program a split screen yourself. This is not the easiest of 
I 1 programming tasks, since it involves raster interrupt processing, which can be tricky. In 

' i C128 mode, bit 6 in the GRAPHM register is the split screen bit. If bit 6 of $0008 

(GRAPHM) is set, a split screen is displayed. Otherwise, bit 6 is clear (0) and a single 
pj screen is displayed. 

J I The C64 mode has no corresponding split screen bit. C64 mode is programmed 

differently for split screens. See the Raster Interrupt Split-Screen Program at the end of 
^^ the chapter to learn how to program a split screen in machine language. 



CAUTION: A system crash may occur if the display mode is changed 
while the interrupt-driven screen editor is enabled. See the Shadow 
Register section for details. 



THE INTERRUPT-DRIVEN SCREEN EDITOR 

The intermediate memory locations, sometimes referred to in this guide as shadow 
registers, are designed specifically for handling the split-screen modes. In order to 
provide split-screen modes, the C128 screen editor has to be wedged into the system's 
interrupt handling routines. 
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Unlike the Commodore 64, the C128 handles interrupts exclusively according to 
the raster beam. This has made it necessary to merge the C128 screen editor into the 
interrupt request routines (IRQ). The C64 uses interrupt timers which makes interrupt 
processing less predictable. By processing the interrupts from the raster beam, the 
operating system always knows where and when the interrupt will occur. Timer inter- 
rupts made catching a raster interrupt less reliable because the operating system never 
knew exactly where an interrupt would occur in relation to the raster beam. 

The raster interrupt-driven screen editor made it necessary to use indirect storage 
locations for certain registers of the VIC chip and 80-column chip. This way, the 
intermediate memory locations refresh the actual video chip registers every sixtieth of a 
second, each time the raster beam begins a new scan at the top of the screen. The raster 
beam scans the entire screen sixty times a second, so on each pass of the raster beam the 
intermediate memory locations refresh the actual VIC chip and 8563 chip registers. 



RASTER INTERRUPT 
SPLIT SCREEN PROGRAM 
WITH HORIZONTAL SCROLLING 








u 





u 



This section explains how and provides a program to perform split screen raster 
interrupts in machine language. The program is explained as it applies to Commodore ] 

64 mode, but it can be modified to run in Commodore 128 mode. 

You already have a way to split the screen in CI 28 mode with the BASIC 
GRAPHIC command. The program provided in this section splits the screen in machine 
language in C64 mode. See the figure in the shadow register section to see which 
addresses must be changed to make this program work in C128 Mode. A few differ- 
ences will occur in the timing of the raster. In Commodore 128 mode, all interrupts 
occur according to the position of the raster beam as it scans the screen. This is why 
shadow registers are necessary for certain graphics locations, since the CI 28 screen 
editor is interrupt driven to allow the split screen modes in BASIC. 

The program in this section also scrolls text on the bottom quarter of a standard 
character screen, while the top three quarters are displayed in multi-color bit map mode. 
The standard character screen resides in video bank ($0400-$07E7) while the multi- 
color bit map video matrix is stored in video bank 1 starting at $5C00 ($1C00 + 
$4000 = $5C00). Every time an interrupt occurs, the program changes video banks, 
display modes, the character memory and video matrix pointers. This program supplies 
the data that scrolls at the bottom of the screen, but it assumes you have placed an 8000 
byte bit map starting at address 8192 ($2000) plus an offset of 16384 ($4000) for the 
change of video banks. This makes the absolute start address of the bit map 24576 ($6000). 

An 8000 byte bit map is just too large to present in this book. However, the easy 
way to place a bit map in this area is as follows: 



U 



L 



I I 
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1. First start in C128 mode, and enter split screen (multi-color) bit map 
mode through BASIC with this command: 

GRAPHIC 4,1 

2. Now draw on the screen with the BOX, CIRCLE, DRAW and PAINT 
commands either in a program or in direct mode. 

3. When you are finished drawing, enter the machine language monitor either by 
pressing the F8 function key or by typing the MONITOR command. 

4. Now transfer the video matrix and bit map from the C128 default locations of 
$1C00 through $1FFF and $2000 through $3FFF respectively, to $5C00 through 
$5FFF and $6000 through $7FFF respectively. The new start addresses are 
the default locations plus an offset of $4000 for both the video matrix and bit 
map pointers. The new start of the video matrix is at $5C00 ($1C00 + 
$4000). The new bit map begins at address $6000 ($2000 + $4000). This 
transfer can be accomplished with a single transfer command within the 
machine language monitor as follows: 

T ICOO 3FFF 5C00 

This command transfers the contents of memory locations $ICOO through $3FFF 
to $5C00 through $7FFF. Since the default locations of the video matrix and bit map are 
continuous in memory, the transfer can be done with a single command. If the default 
addresses of the video matrix and bit map had not been contiguous, two transfers would 
have been necessary. See Chapter 6 for details on using the Machine Language Monitor. 



Now that you are still within the control of the Machine Language Monitor, begin 
entering the machine language instructions in the listing provided in the next few pages. 
Start entering the program at address $OCOQ. The program, including the scrolled data 
occupies memory up to address $0DF9, which means the program is a total of 505 bytes, 
or almost half a kilobyte (K). 

Now save the program you just painstakingly entered with the Monitor Save (S) 
command as follows: 

S "filename", 08, OCOO, ODFF 

If you have a C128 assembler, create a source file, assemble and load it. If your 
assembler allows it, save the program as a binary file. 



NOTE: If you have the Commodore 64 Assembler Development System, 
create a source file (with start address $GC00), assemble and load it in 
C64 mode. Then press the RESET button (not the ON/OFF switch) to enter 
C128 mode. Don't worry, your program will still be in memory, but this 
time it's in C128 memory. Next enter the Machine Language Monitor 
and use the Monitor Save (S) command to make a binary file as described 
above. 
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Now you are ready to enter C64 mode and run the program with the following 
command: 

GO 64 

Reply to the question "ARE YOU SURE?" by pressing the "Y" key and 
RETURN. You are now placed in C64 mode. 

At this point, you may say to yourself, "After I just did all that work, why am I 
going to waste it by changing modes?" 

Actually, you are not wasting any effort. When you GO 64 (or press the reset 
button), much of the RAM for machine language programs and data is preserved in 
RAM bank 0. BASIC programs are erased, however. Specifically, these are the ranges 
of RAM that are preserved when changing between C128 and C64 modes: 



C128 MEMORY LAYOUT 

$0C00 • $ODFF RS232 Input and Output Buffers 

$1300 - $1BFF Available Memory for Machine Language application programs 

$1C00 - $1FFF Bit Map Video Matrix 

$2000 - $3FFF Bit Map Data 

$4000 - $FFOO BASIC Text Area 

Figure 8-27. Preserved RAM Between CI 28 and C64 Modes 







w 

^ 



u 

lJ 



The rest of the RAM memory is allocated for other purposes and the contents . , 

change from mode to mode. There are other particular bytes that are preserved from j ( 

mode to mode, but these small chunks of memory are not worth mentioning here. The ^ 

blocks of memory mentioned above provide enough of a clue to the RAM used by both 
modes. Remember, however, that the RAM is only preserved if you switch from CI 28 j [ 

mode to C64 mode with the GO 64 command, or you switch from C64 to CI 28 mode '-' 

with the reset button (warm start). If you perform a cold start, turn the computer power 
off, then on again, all RAM is cleared and none is preserved. ^ 

Notice that the address ranges where you placed your program, the video L 

matrix and the bit map are in the portions of RAM that are preserved from mode to 
mode. 



li 



Now start (run) the program from C64 BASIC with this command: 

SYS 12*256 jj 

The top three quarters of the screen is the bit map screen you created with the 
C128 BASIC graphics commands, the lower quarter is horizontally scrolling text. 1 

The following program is the listing that performs the split screen and scrolling. L 
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1000 

1010 

1020 

1030 

1040 

1050 

1060 

1070 

1080 

1090 

1100 

1110 

1120 

1130 

1140 

1150 

1160 

1170 

1180 

1190 

1200 

1210 

1220 

1230 

1240 

1250 

1260 

1270 

1280 

1290 

1300 

1310 

1320 

1330 

1340 

1350 

1360 

1370 

1380 

1390 

1400 

1410 

1420 

1430 

1440 

1450 

1460 

1470 

1480 

1490 

1500 

1510 

1520 

1530 

1540 

1550 

1560 

1570 

1580 

1590 

1600 

1610 

1620 

1630 

1640 

1650 

1660 

1670 

1680 



; RASTER INTERRUPT SPLIT SCREEN WITH HORIZONTAL SCROLLING 

IVEC=$0314 

TEMP=S1806 

RASTRO=SD012 

BACOL=SD021 

POINT=S1802 

FLAG=$FC 

FLAG2=SFD 

SCROLL=SFE 

SREG=$D016 

TXTPTR =$FA 



; POINTER INTO SCROLLING TEXT 



*=$0C00 



LDA #<FRANK ; POINT TO TEXT 
STA TXTPTR 
LDA #> FRANK 
STA TXTPTR+1 

LDA #$07 ;SET HI VAL SREG 
STA SCROLL 
STA FLAG 2 

LDA $DD02 ;SET TO OUTPUT 
ORA #$03 
STA $DD02 



LDA $D016 ;SET 38 COL. 
AND #$F7 
STA SD016 



LDA #$01 ; CLEAR CRAM 
LDX #$00 
BONK STA $DB20,X 
INX 

CPX #200 
BNE BONK 



INITIALIZE INTERRUPT 



LOOP! 

LDA 
STA 
LDA 
STA 
LDA 
STA 
LDA 
STA 



SEI 

IVEC 

TEMP 

IVEC+1 

TEMP+1 

#<MINE 

IVEC 

#>MINE 

IVEC+1 



LDA #$00 ; DISABLE TIMER IRQ 
STA $DCOE 
STA FLAG 

'lDA #49 
STA POINT 
STA RASTRO 

'lDA #201 
STA POINT+1 



LDA #1 

STA $D01A ; ENABLE INTERRUPT 
STA $D019 ; RASTER COMPARE 
LDA $D011 ;CLEAR HI BIT 
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1690 


AND 


#$7F 




1700 


STA 


SDOll ;DISABLE INTRPT DIS BIT 




1710 ; 








1720 


CLI 






1730 ; 








1740 ; 








1750 ; 








1760 ; 








1770 C 


HECK 


LDA FLAG2 




1780 


BPL 


CHECK 




1790 


LDA 


#$00 




1800 


STA 


FLAG 2 




1810 ; 








1820 


LDX 


#39 




1830 


LDY 


#39 




1840 £ 


HIFT 


LDA ( TXTPTR ),Y 




1850 


STA 


S0770,X 




1860 


DEX 






1870 


DEY 






1880 


BPL 


SHIFT 




1890 


INC 


TXTPTR 




1900 


BNE 


MVTIME ;TIME TO RESET POINTER 




1910 


INC 


TXTPTR+1 




1920 MVTIME LDA TXTPTR ;ARE WE AT THE END OF THE TEXT YET 


7 


1930 


CMP 


#<ENDTXT 




1940 


BNE 


CHECK 




1950 


LDA 


TXTPTR+1 




1960 


CMP 


#> ENDTXT 




1970 


BNE 


CHECK 




1980 


LDA 


#<FRANK ;SET POINTER BACK TO THE BEGINNING 




1990 


STA 


TXTPTR 




2000 


LDA 


#> FRANK 




2010 


STA 


TXTPTR+1 




2020 


JMP 


CHECK 




2030 








2040 FRANK .BYT 




2050 


.BYT ' 




2060 


.BYT 'THIS IS AN EXAMPLE OF SCROLLING 




2070 


.BYT 'IN THE HORIZONTAL (X) DIRECTION. 




2080 


.BYT 'ONCE THE DATA HAS BEEN DISPLAYED, 




2090 


.BYT 'SCROLLING STARTS AGAIN FROM THE 




2100 


.BYT 'BEGINNING. ' 




2110 








2120 


ENDTXT .BYT 




2130 


.BYT 




2140 








2150 


• INTERRUPT SERVICE ROUTINE 




2160 








2170 


ilNE 


LDA $D019 




2180 


STA 


SD019 




2190 








2200 


'lda 


FLAG ;FLAG =0 .A=0 




2210 


EOR 


#1 ;ELAG =0 .A=l 




2220 


STA 


FLAG ;FLAG =1 .A=l 




2230 


TAX 


; .X=l .A=l 




2240 


LDA 


POINT, X ;.X=1 .A=200 




2250 


STA 


RASTRO ;.X=1 RASTRO=200 




2260 


CPX 


#1 




2270 


BNE 


BOTTOM 




2280 








2290 


'lda 


SDOll ;BIT MAP MODE 




2300 


ORA 


#?20 




2310 


STA 


SDOll ;BMM 




2320 


LDA 


SDOIS 




2330 


ORA 


#S78 ;CHAR=$2000+$4000 




2340 


STA 


$D018 ;SCR=S1C00+S4000 




2350 


LDA 


SD016 




2360 


ORA 


#S10 




2370 


STA 


SD016;SET MULTICOLOR 





u 






\} 



u 



u 



u 
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2380 


; 




2390 


LDA 


$DDO0 ; SELECT BANK 1 


2400 


AND 


#$FE 


2410 


STA 


$DDOO 


2420 


; 




2430 


LDA 


SREG ;SET SCRRREG 


2440 


AND 


#$F8 


2450 


ORA 


#$03 


2460 


STA 


SREG 


2470 


; 




2480 


LDA 


#14 


2490 


STA 


$D021 


2500 


; 




2510 


PLA 




2520 


TAY 




2530 


PLA 




2540 


TAX 




2550 


PLA 




2560 


RTI 




2570 


• 




2580 


; 




2590 


BOTTOM LDA $D011 ; SET TEXT MODE 


2600 


AND 


#$FF-$20 


2610 


STA 


$D011 


2620 


; 




2630 


LDA 


$DD00 .-CHANGE TOBANK 


2640 


ORA 


#S01 


2650 


STA 


$DDOO 


2660 


; 




2670 


LDA 


$D016 ; DISABLE MOLTI 


2680 


AND 


#$FF-$10 


2690 


STA 


$D016 


2700 


; 




2710 


LDA 


#23 ; MEMORY 


2720 


STA 


$D01B 


2730 


; 




2740 


LDA 


#$00 


2750 


STA 


$D021 


2760 


LDA 


SCROLL 


2770 


; 




2780 


; 




2790 


DEC 


SCROLL 


2800 


LDA 


SCROLL 


2810 


STA 


FLAG 2 


2820 


CMP 


#$FF 


2830 


BNE 


SLURP 


2840 


LDA 


#$07 


2850 


SLURP STA SCROLL 


2860 


LDA 


SREG 


2870 


AND 


#$FF-$07 


2880 


ORA 


SCROLL 


2890 


STA 


SREG 


2900 


BASIRQ JMP (TEMP) 


2910 


• 




2920 


.END 





For readability, the program is listed as a source file, as though it was entered 
through an assembler editor. It is easier to understand as a source file rather than a 
listing from the Machine Language Monitor. To enter this program into the Machine 
Language Monitor, reference the actual address in place of the variable operand ad- 
dresses. Most of the actual addresses are listed in the beginning of the program (lines 
1010 through 1100). Keep in mind that these are only line numbers for an assembler 



! ! 
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editor. You will enter the program into a memory location number (address) in the 
Machine Language Monitor. In this case, the program is stored in memory starting at 
address $0C00. Line 1 120 specifies this start address with: 







u 



u 



u 



* = $ocoo 

Here's an instruction-by-instruction explanation of the scrolling split screen program. 

Line 1010 assigns the variable IVEC to the address $0314, the hardware interrupt 
request (IRQ) vector. The interrupt vector is the means by which the Commodore 128 
displays split screens and scrolling. By wedging your own routine into the hardware 
interrupt vector (in this case scrolling and splitting the screen), it enables you to perform 
operations that usually take too long for the microprocessor to perform under an 
application program not using interrupts. The interrupt vector is checked for an interrupt 
routine every 60th of a second. In this program, the screen is split 60 times per second, 
so it appears you have two different screens displayed at the same time. You could not 
split the screen without requesting an interrupt; the microprocessor is not able to perform 
all the required operations fast enough to keep up with the raster scan of the video ^ 

controller. The speed that the screen is continually updated, known as the raster scan, I | 

also occurs at the speed of 60 times per second. For a split screen to occur, you tell the ^ 

computer the point on the screen where one type of display ends and the new one (bit 
map for example) begins. The way you tell the computer this is by placing the number j I 

of a pixel row, also called a raster row, in the raster compare register located at address [J 

$D012. Line 1030 assigns this address to the variable RASTRO. 

You'll see later in the program that the value placed in the Raster Compare Register \ 

starts the text screen at raster row 201. The raster scan is again interrupted at raster row * 

50 at the top of the screen to display the bit map screen. This is repeated 60 times every 
second, so it appears to the human eye that two different display modes are active at the 
same time. I j 

On with the program explanation. Line 1040 defines the BACOL variable for the ^ 

background color register zero, located at address $D021. Line 1050 assigns the variable 
POINT to location $1802. POINT is used to store the raster row value where the text I | 

screen begins. Line 1060 assigns the variable FLAG to location $FC. FLAG is used later ^ 

in the program (lines 2200-2270) to determine where the interrupt occurred, either raster 
row 50 or raster row 200. \ j 

Lines 1070 and 1080 assign the variables FLAG2 to location $FD and SCROLL to IJ 

location $FE respectively. Both FLAG2 and SCROLL store the value of the scrolling 
register. SREG is assigned to location $D016, the scrolling register. Only bits through , i 

2 are used as the scrolling bits. The other bits in this address are used for other ! i 

purposes. Three scrolling bits are necessary since characters that are scrolled are moved 
over seven pixels then shifted to the next character position to the left or right, then 
scrolled smoothly again seven more pixels. ) ( 

Line 1100 assigns the variable TXTPTR to address $FA. This variable marks the *-' 

starting address in memory where the scrolled characters are stored. 

As was mentioned earlier, line 1 120 specifies where the program storage begins in \ I 

memory. This is the address where the execution of the program begins in memory. You LJ 



I 1 



I I 
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will SYS to this address to start the program in BASIC, or GO to this address from the 

Machine Language Monitor. 
I I The first sequence of program instructions starting at line 1 140 places the contents 

' * of the address (named FRANK) of the beginning of the scrolling text into the memory 

locations ($FA and $FB) called TXTPTR and TXTPTR+ 1. FRANK is the label in line 
j~] 2040 which marks the location where the first scrolled character is stored. In this 

', [ program the first character is a space; in fact the first forty characters that are scrolled 

across the screen are spaces. The forty-first character marks the beginning of the data 
rm, 'THIS IS AN EXAMPLE OF SCROLLING' in line 2060. The scrolled data in lines 

' ; 2040 through 2130 is stored starting at location $0C98, once this source file is 

' ' assembled into object code. In this case, the low byte stored in $FA is $98 and the high 

stored in $FB is $0C. The full 16-bit address $0C98 is important, since this is the base 
n address which you increment as you scroll each letter across the VIC screen. When the 

I I text pointer (TXTPTR) reaches the end of the scrolling text, the base address $0C98 is 

again stored in TXTPTR. 



n 



The second sequence of instructions starting at line 1 190 sets the high value of the 
two scrolling variables SCROLL ($FE) and FLAG2 ($FD) to 7. These are used and will 

^^ be explained later in the program. 

I j Sequence three starting at line 1230 sets the data direction register to output. 

' ' The next module of instructions in lines 1280 through 1300 set the screen size to 

38 columns, reducing the screen width by a column on each side. In order to scroll 

r^ smoothly, you must set the screen size to 38 columns. Clearing bit 3 of location $D016 

i » sets 38 column size. Setting bit 3 restores the VIC screen to its normal 40 column size. 

The extra column on each side of the screen border provides a place for the 

n scrolled data to scroll smoothly to and from offscreen. This program scrolls left, so each 

J j newly scrolled character is placed in column 39 on the right, before it becomes visible in 

column 38. At the same time, the lead character on the left scrolls from column 2 to 

r-) offscreen column 1. This occurs in lines 1770 through 2020 and is explained as the 

' j program progresses. 

Lines 1330 through 1380 set the text screen color RAM to a white fore- 
i , ground. The lower four bits specify the foreground character color in standard 

' * character mode. 

The screen memory is stored in video bank where the scrolling text appears at 
r^ the bottom fourth of the screen. The bit map and video matrix are stored in video bank 

li 1, the 16K range between $4000 and $7FFF. 

The reason only 200 color RAM locations are filled is because only the lower five 
p rows are visible on the text screen. There is no point clearing the other 800 locations 

j j since they are not visible. 

^ Lines 1410 through 1700 make up the interrupt initialization routine. Line 1430, 

! I labeled LOOPl, sets the interrupt disable bit in the status register. When this bit is set, 

interrupts are disabled and none can occur. Only when the interrupt disable bit is cleared 
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(0) can interrupts occur. The last line (1720) of the interrupt initialization routine clears 
the interrupt disable and allows interrupts to occur. 

Lines 1440 through 1470 store the original contents of the Interrupt Request (IRQ) 
vector into temporary storage locations TEMP (low byte $1806) and TEMP+1 (high 
byte $1807). This is necessary in order to store the original contents of the IRQ vector 
so you can jump back to this location once the interrupt is serviced as in line 2900. 

Lines 1480 through 1510 store the starting location of the interrupt service routine 
into the IRQ vector. In this case, MINE is the source file label in line 2170 where the 
interrupt service routine begins. In the assembled object file, as in the Machine 
Language Monitor, the low byte is $71 and the high byte is $0D, to form the 16 bit 
address $0D71. Once the interrupt disable bit is cleared and an interrupt occurs, the 
8502 microprocessor finishes executing its current instruction and sets the interrupt 
disable status bit, so no other interrupts can occur. The processor then places the 
contents of the high byte and low byte of the program counter and the status register on 
the stack respectively. Finally, the 8502 fetches the address contained in the IRQ vector 
and executes the routine starting at this address, in this case $0D71. 







\ { 



1! 



I I 



Lines 1530 and 1540 disable the CIA timer in location $DCOE. In addition, line 
1550 initializes the variable FLAG to zero. This variable is used later in the program to 
figure out where the raster interrupt has occurred, either at the top of the screen (raster 
row 49) for bit map mode or near the bottom fourth of the screen (raster row 201) for 
standard character mode. 

The instructions in lines 1570 through 1590 define the variable POINT ($1802) as \ | 

the value of the raster row 49 ($31) where the interrupt occurs to select bit map mode. In jj 

addition, this value is also stored in the Read/Write Raster Register ($D012) for raster 
row comparisons later in the program. ^ 

The CI 28 VIC screen consists of 200 raster rows, each row one pixel tall, having 1 j 

320 pixel columns. You know how BASIC addresses the bit map coordinates on a '"' 

coordinate plane of 0,0 in the top left comer and 3 19, 199 in the bottom right. However, 
the visible raster rows are not labeled in the same way. The visible raster rows start at | ! 

50 at the top of the screen and end at 250 at the bottom. These are the same row i_j 

numbers as sprites use. Notice there are still 200 rows but that they offset the bit map 
coordinate row number by 50. The raster row numbers below 50 and above 250 are off \ / 

the visible screen. These offscreen raster rows are referred to as the vertical retrace. M 

The instructions in lines 1610 and 1620 define the variable POINT + 1 ($1803) as 
the value of the raster row 201 ($C9) where the interrupt occurs to select standard 
character mode. j { 

Lines 1650 and 1660 enable the raster IRQ Mask Register. Line 1670 sets the '—' 

Raster Compare IRQ Flag. By setting bit one in these registers, the raster interrupt 
attached to the IRQ line is allowed to occur (once lines 1680 through 1720 are j j 

executed), depending upon whether the physical raster row compares and matches with |_j 

either of the values in POINT or POINT+ 1. If either of these match, the interrupt 
occurs. , 

The instructions in lines 1680 through 1700 clear the raster compare high bit (bit { 

8). This is an extra bit from location $D012 for raster compares. 



/ ! 



/ I 
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The instruction in line 1720 clears the interrupt disable status bit, which enables 
interrupts to occur. This is the last operation to be performed by the interrupt initializa- 
tion routine. Now interrupts are ready to occur and be serviced. 



Lines 1770 through 1800 check the value of FLAG2. If FLAG2 is positive, the 
program branches to the label CHECK in line 1770 and checks the value of FLAG2 
again. The value stored in FLAG2 represents the value of the lower three bits in the 
horizontal scrolling register at location $D016. The variable SCROLL is also associated 
with the variable FLAG2. In the interrupt service routine (in lines 2760 through 2810), 
the value in SCROLL is decremented and stored in FLAG2. This value pertains to the 
value placed in the actual horizontal scrolling register at $D016. The reason this is 
counted is as follows. 
p The direction of the scrolling is right to left; therefore, you must place the 

) i maximum value (7) in the lower three bits of $D016 and decrement that value by one. If 

the program had scrolled left to right, you would initialize the scrolling register to zero 
and increment the lower three bits. When the scrolling register value is decremented, the 
characters in the screen memory locations which are to be scrolled are moved to the left 
by one pixel. Each time the scrolling register is decremented, the characters move 
another pixel to the left. When the value (the lower three bits) of the scrolling register 
n equals zero, you must move the scrolled characters up in screen memory by one location. 

This routine is contained in lines 1840 through 1880. After the shift, the lower three bits 
of the scrolling register are set back to 7, the characters are again shifted by the VIC 
chip 7 pixels to the left and your routine shifts the characters up in memory again by 
one. The additional details are covered in the explanation of lines 2760 through 2900. 

The instructions in lines 1820 through 1880 shift the text to be scrolled up in 
memory by one location for each cycle of the loop. First the X and Y registers are 
loaded with the decimal value 39 ($27). The instruction in line 1840 loads the value of 
the memory location where the scrolled text begins using indirect Y addressing. The 
address is calculated by taking the contents of zero page memory variable TXTPTR 
($98) and adding the offset 39 to its contents to arrive at $BF. The effective address 
gives the low byte where the scrolled data begins. The first scrolled character is actually 
a space. Subsequent data elements are accessed by modifying the value of the Y register. 
The store instruction in line 1850 stores the first character of the scrolling text in 
screen location 1943 ($0770 + $27), which is the fortieth column of the twenty-third 
row. This column is not visible when the screen size is set to 38 columns for horizontal 
scrolling. Each newly scrolled character must be placed in this position in order to scroll 
smoothly from the offscreen location. Lines 1860 and 1870 decrement the X and Y 
registers respectively. Line 1880 branches to the label SHIFT if the Y register is positive 
(greater than zero). 

The second time through the loop, the low byte of the scrolled character (at 
location $98 + $26 = $BE) is stored in screen location 1942 ($0770-1- $26), so the 
(space) character in $OCBE is stored in screen location $0796. The third time through 
the loop, $0CBD is stored in $0795 and so on. This process continues until the X and 
Y registers equal zero. So far, only the series of 39 space characters in lines 2040 and 
2050 have been shifted across the screen. 
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THE INTERRUPT SERVICE ROUTINE 






Once the X and Y registers have been decremented to zero, the TXTPTR is 
incremented in line 1890 so that subsequent characters such as "THIS IS AN EXAM- 
PLE . . ." can be scrolled. In the first 39 cycles through the loop (in lines 1840 through 
1880) 39 spaces are shifted (scrolled) one character position on the twenty-third character 
row on the screen. The next 39 cycles shift 38 spaces and the letter "T" in "THIS" one 
character position across the screen. The next 39 cycles, 37 spaces and the letters "TH" 
in "THIS" are shifted in memory and scrolled one character position on the screen and 
so on. This process occurs until all characters in the data (in lines 2040 through 2130) 
are scrolled. 

Line 1900 branches to the label MVTIME while TXTPTR (the low byte of the 
start of scrolled data) is greater than zero, otherwise TXTPTR + 1 incremented to update 
the high byte. Lines 1920 through 1970 check to see if the text pointers are at the end of 
the scrolled character data ($0D70 in the assembled program). If the pointers are not at 
the end of the character data, the program branches to the label CHECK and the data is 
shifted by the VIC chip by seven pixels and the scrolling process repeats again. If the 
text pointers are at the end of the scrolled character data, lines 1980 through 2010 set the 
text pointers to the beginning of the scrolled data in memory and the process is repeated 'w' 

continuously as specified by the JMP CHECK instruction. 

Lines 2040 through 2130 represent the data to be scrolled by the program. The [J 

data is stored in .BYTE statements as it appears in the Commodore Assembler 64 
Development System. In your case, the Machine Language Monitor handles data by 
simply storing it in an absolute memory range. In the assembled object code program \ | 

the data turns out to be stored in the range $0C98 through $0D70. You will refer to the ^ 

data with these addresses and not with a label as in this explanation. 



i_j 



y 

The program instructions in lines 2170 through the end of the program make up the ( i 

interrupt service routine. Depending upon the value of the raster comparison, particular j ' 

segments of the routine are executed upon the detection of an interrupt. For instance, if 

the result of the raster comparison detects an interrupt to occur at raster row 49, lines 

2290 through 2560 are executed. This selects bit map mode and performs additional ] I 

functions that are explained in a moment. If the raster comparison detects the interrupt 'J 

to occur at raster row 201, lines 2590 through 2900 are executed. These instructions 

select standard character mode, among other things. Keep in mind that both segments of 

the interrupt service routine are executed within a single, complete raster scan of the 

screen sixty times per second. Instructions 2170 through 2270 are always executed when 

an interrupt occurs. 

The instruction in line 2170 clears the raster compare IRQ flag after the interrupt j | 

has occurred. The address of the label MINE, which is loaded into the IRQ vector in '-' 

lines 1480 through 1510, tells the 8502 where the interrupt service routine resides upon 
the occurrence of an interrupt. In the assembled object code, this is an absolute address 1 I 

($0D71). iJ 

u 
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Lines 2200 through 2270 determine the location (raster row) in which the raster 

interrupt has occurred. Line 2200 loads the value of FLAG, which was initialized to 

zero, into the accumulator. Line 2210 XOR's the accumulator with 1, which effectively 

places a one in the accumulator for the first pass through this routine. This value is then 

stored back into FLAG. In each subsequent occurrence of an interrupt, the value of both 

the accumulator and FLAG are toggled between zero and one. The accumulator is then 

transferred to the X register in line 2230. Line 2240 loads the value of POINT or POINT 

+ 1 depending upon the value in the X register. If the X register equals 0, POINT is 

loaded into the accumulator, which specifies the interrupt to occur at raster row 49. If 

the X register equals 1, POINT + 1 is loaded into the accumulator, which specifies the 

f i interrupt to occur at raster row 201. Line 2250 stores the accumulator value into the 

variable RASTRO. The X register is compared with 1 in line 2260. If the X register 

pt equals 1, the interrupt has occurred at raster row 201 and the program branches to the 

\ j instructions in lines 2590. If the value of the X register equals 0, the branch in line 2270 

falls through and the instructions in lines 2290 through 2650 are performed. 

The instructions in lines 2290 through 2560 perform the operations associated with 
j 1 bit map mode. Lines 2290 through 2310 select bit map mode. Lines 2320 through 2340 

' ' set the video matrix at $1C00 and the bit map at $2000. Both of these start addresses are 

offset by the compulsory $4000, since this screen appears in video bank 1 ($4000-$7FFF). 
p Lines 2350 through 2370 set multi-color mode. Lines 2390 through 2410 select video 

1 I bank 1. Lines 2430 through 2460 set the lower two bits of the scrolling register (to the 

value 3). 
p The instructions in 2510 through 2550 restore the original values of the X, Y and 

i ] A (accumulator) registers. Line 2560 returns from the interrupt and exits the interrupt 

service routine. 
_ Lines 2590 through 2900 perform all the associated text mode operations. Lines 

n 2590 through 2610 select standard character mode. Lines 2630 through 2650 changes 

' ' back to video bank 0, the default bank ($0000-$3FFF). Lines 2670 through 2690 disable 

multi-color mode, and return to the standard color mode. Lines 2710 and 2720 set the 
n default screen location 1024 ($0400) and the default start of character memory, with the 

■ I decimal value 23 ($17). All numbers which are not preceded by a dollar sign are 

assumed to be decimal in this particular assembler editor. Lines 2740 and 2750 set the 
P^ background color for the text screen to black. 

i i Lines 2760 through 2890 set the value of the scrolling register, which scrolls the 

characters across the screen by 7 pixels, before they are shifted in memory with the 
r* routine in lines 1840 through 1880. 

Finally, line 2900 jumps to the default IRQ vector which was saved early in the 
program into the variable TEMP. This allows the 8502 to process the normal interrupt 
services as though this program's service routine had not occurred. 

Although this program example is long and complex, it contains useful routines 
and explanations that have never appeared before in any Commodore text. Study these 
routines carefully and add them into your own programs. This section includes a wealth 
of information for the novice and experienced software developer alike. Figures 8-28 
through 8-32 on the following four pages provide a summary of graphics programming. 
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CHANGING VIDEO BANKS 


MOVING SCREEN RAM 


CI28 
BASIC 


POKE S6S76, (PEEK (56576) 
AND 252) OR X 

WHERE X IS THE DECIMAL 
VALUE OF BITS AND 1 IN 
TABLE 8-30 ON PAGE 262 


TEXT 

POKE 2604, (PEEK(26(M AND IS) 
ORX 

WHERE X IS THE DECIMAL 

VALUE IN TABLE 8-29 ON P. 262 

BITMAP 

POKE 2605, (PEEK(2605 AND 15) 
ORX 

WHERE X IS A VALUE IN 
TABLE 8-29 ON P. 262 


CI28 

MACHINE 

LANGUAGE 


LDA $DDOO 
AND#$FC 
ORA #$X 
STA $DDOO 

WHERE X IS THE HEX VALUE 
OF THE BITS IN TABLE 8-30 ON 
P. 262 


TEXT BIT MAP 

LDA$0A2C LDA$0A2D 

AND #$0F AND #$0F 
ORA #$X ORA #$X 
STA$0A2C STA$0A2D 

WHERE X IS A HEX EQUIVA- 
LENT OF THE DECIMAL 
VALUE IN nOURE 8-29 ON P. 
262 


C64 
BASIC 


POKE 56576, (PEEK (56576) 
AND 252) OR X 

WHERE X IS THE DECIMAL 
VALUE OF BITS and 1 IN 
TABLE 8-30 on P. 262 


TEXT OR BIT MAP 

POKE 53272, (PEEK(53272) 
AND 15) OR X 

WHERE X IS A DECIMAL 
VALUE IN nOURE 8-29 ON P. 
262 


C64 

MACHINE 

LANGUAGE 


LDA $DDOO 

AND #$FC 
ORA #$X 
STA $DDOO 

WHERE X IS THE HEX VALUE 
OF BITS AND 1 IN 
TABLE 8-30 ON P. 262 


TEXT OR BIT MAP 

LDA $D018 

AND#$OF 
ORA #$X 
STA $D018 

WHERE X IS A HEX 

EQUIVALENT OF THE DECIMAL 
VALUE IN HGURE 8-29 ON P. 
262 

IN C64 MODE, YOU CAN SET 
UP TWO DIFFERENT SCREENS, 
ONE FOR TEXT AND THE 
OTHER FOR BIT MAP, AS THE 
C128 KERNAL DOES. 
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Figure 8-28. Graphics Programming Summary — PART I 
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MOVING CHARACTER MEMORY 


ACCESSING CHARACTER ROM 


TEXT 

POKE 2604, (PEEK(2604)AND 240) OR Z 

BITMAP* 

POKE 2605, (PEEK (2605)AND 240) OR Z 

WHERE Z IS A DECIMAL VALUE 
INHGURE8-310NP. 262 

*= ONLY BIT 3 IS SIGNIHCANT 
IN BIT MAP MODE 


10 BANK 14: REM SWAP IN CHAR ROM 
20 FOR 1 = TO 7 
30 ? PEEK a) 
40 NEXT 
50 BANK 15 


TEXT BIT MAP* 

LDA$0A2C LDA$0A2D 

AND #$F0 AND #$F0 
ORA #$Z ORA #$Z 
STA $0A2C STA $0A2D 

WHERE Z IS THE HEX EQUIVALENT OF 
A DECIMAL VALUE IN HGURE 8-31 ON 
P. 262 

* = ONLY BIT 3 IS SIGNMCANT IN BMM 


LDA #$01 
STA $FFOO 
LDX #$00 
LDA #$DOOO,X 
LOOP STA $TEMP,X 
INX 

CPX #$07 
BNE LOOP 
LDA #$00 
STA $FFOO 


TEXT OR BIT MAP* 

POKE 53272, (PEEK(53272)AND240) OR Z 

WHERE Z IS A DECIMAL VALUE IN 
HGURE 8-31 ON P. 262 

* = ONLY BIT 3 IS SIGNIHCANT 
IN BIT MAP MODE 


5 TEMP = 6144 

10 POKE 56334,PEEK (56334) AND 254 

20 POKE 1, PEEK (1) AND 251 

30 FOR 1 = TO 7 

40 POKE (TEMP + I, PEEK (53248 + I) 

50 NEXT 

60 POKE 1, PEEK (1) OR 4 

70 POKE 56334, PEEK (56334) OR 1 

80 FOR I = TEMP TO TEMP -1- 7 

90 ? PEEK a); 

100 NEXT 


TEXT OR BIT MAP* 

LDA $D018 

AND#$FO 
ORA#$Z 
STA $D018 

WHERE Z IS THE HEX EQUIVALENT 
OF A DECIMAL VALUE IN FIGURE 
8-31 ON P. 262 

* = ONLY BIT 3 IS SIGNIFICANT 
IN BIT MAP MODE 


LDA $DCOE 
AND#$FE 
STA $DCOE 
LDA $01 
AND#$FB 
STA $01 
LDX #$00 
LOOP LDA $D000,X 
STA $TEMP,X 
INX 

CPX #$07 
BNE LOOP 
LDA $01 
ORA #$01 
STA $01 
LDA $DCOE 
ORA #$01 
STA $DCOE 



Figure 8-28. Graphics Programming Summary — PART 2 
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LOCATION* 


X 


BITS 


DECIMAL 


HEX 





ooooxxxx 





$0000 


16 


oooixxxx 


1024 


$0400 (DEFAULT) 


32 


ooioxxxx 


2048 


$0800 


48 


OOllXXXX 


3072 


$0C00 


64 


OlOOXXXX 


4096 


$1000 


80 


OIOIXXXX 


5120 


$1400 


96 


OUOXXXX 


6144 


$1800 


112 


OlllXXXX 


7168 


$1C00 


128 


lOOOXXXX 


8192 


$2000 


144 


lOOlXXXX 


9216 


$2400 


160 


lOlOXXXX 


10240 


$2800 


176 


lOllXXXX 


11264 


$2C00 


192 


llOOXXXX 


12288 


$3000 


208 


IIOIXXXX 


13312 


$3400 


224 


lllOXXXX 


14336 


$3800 


240 


llllXXXX 


15360 


$3C00 



♦Remember that the BANK ADDRESS offset of $4000 for each video 
bank above zero must be added to the screen memory address. 

Figure 8-29. Screen Memory Locations 



BANK 


1 

2 
3 



ADDRESS RANGE 

$0-$3FFF 
$4000-$7FFF 
$8000-$BFFF 
$C000-$FFFF 



VALUE OF BITS 1 & IN $DDOO 
BINARY DECIMAL 

11=3 (DEFAULT) 
10 = 2 
01 = 1 
00 = 



u 



1 J 



Figure &-30. Video Banl< Memory Ranges 
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LOCATION OF CHARACTER MEMORY* 



VALUE 
OFZ 



BITS 



DECIMAL HEX 





2 
4 



XXXXOOOX 
XXXXOOIX 
XXXXOIOX 




2048 
4096 



$0000-$07FF 
$0800-$0FFF 
$100(^17FF 



ROM IMAGE in BANK & 2 

(default)'^ 

ROM IMAGE in BANK & 2* 



6 XXXXOllX 6144 $1800-$1FFF 

8 XXXXIOOX 8192 $2000-$27FF 

10 XXXXIOIX 10240 $2800-$2FFF 

12 XXXXllOX 12288 $3000-$37FF 

14 XXXXlllX 14336 $380(^3FFF 

Remember to add an offset of $4000 to the start address of character memory for each 
bank above 0; for bank 3 add 3*$4000 = $C000 

* = in C64 mode onl y. 

Figure 8-31. Character Memory Locations 
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SCREEN DATA 


COLOR DATA 


CHARACTER DATA 




TEXT 


BITMAP 


TEXT 


BITMAP 


TEXT 


BITMAP 


C128 BASIC 


1024-2023 


7168-8167 


55296-56295 


♦TAKEN 


53248-57343 


8192-16383 


(DEFAULTS) 


($0400-$07E7) 


($1C00- 


($D800- 


FROM BIT 


(SDOOO- 


($2000-$3FFF) 






$1FE7) 


$DBE7) 


MAP VIDEO 
MATRIX 


$DFFF) 




C128 


1024-2023 


7168-8167 


55296-56295 


♦TAKEN 


TEXT 


8192-16383 


MACHINE 


($0400-$07E7) 


($1C00-$1FE7) 


($D800- 


FROM BIT 


53248-57343 


($2000-$3FFF) 


LANGUAGE 


THIS IS 
ALSO PRO- 
GRAMMABLE 


THIS IS 
ALSO PRO- 
GRAMMABLE 
SEE 

GRAPHICS 
SUMMARY 


$DBE7) 


MAP VIDEO 
MATRIX 


($D000- 
$DI<H-) 


THIS IS 
ALSO PRO- 
GRAMMABLE 
SEE 

GRAPHICS 
SUMMARY 


C64 BASIC 


1024-2023 


1024-2023 


55296-56295 


♦TAKEN 


ROM IMAGE 


NO DEFAULT 


(DEFAULTS) 


($0400-$07E7) 


($040a-$07E7) 


($D800- 


FROM BIT 


IS AT 


MUST 








$DBE7) 


MAP VIDEO 


4096-8191^ 


BE PRO- 




THIS IS 






MATRIX 


($1000- 


GRAMMED 




ALSO PRO- 








ISFFF) 


SEE 




GRAMMABLE 










GRAPHICS 
SUMMARY 


C64 


1024-2023 


1024-2023 


55296-56295 


♦TAKEN 


ROM IMAGE 


NO DEFAULT 


MACHINE 


($0400-$07E7) 


($0400-$07E7) 


($D800- 


FROM BIT 


IS AT 


MUST BE 


LANGUAGE 


THIS IS ALSO PROGRAM- 
MABLE 


$DBE7) 


MAP VIDEO 

MATRDC 

UPPER 


4096-8191^ 
($1000-$1FFF) 


PRO- 
GRAMMED 
SEE 










NYBBLE= 




GRAPHICS 










FOREGROUND 




SUMMARY 










LOWER 


• = actual characler 












NYBBLE= 


ROM location = 

53248-57343 












BACKGROUND 


(SDOOO-DFFF) 





Figure 8-32. Default Graphics Memory Locations 



NOTE: These locations pertain to video bank zero (0) only. 



n 

n 
n 



u 



I 

U 



u 



U 

u 



9 



n 



n 

n 



SPRITES 



n 
n 
n 
n 

n 



n 
n 
n 
n 



265 



266 COMMODORE 128 



SPRITES: 

MOVABLE OBJECT BLOCKS 



u 



A sprite is a movable bit-mapped object that you can define into a particular shape for 
display on the screen. The sprite image can be as large as 24 pixels wide by 21 pixels 
tall. Each pixel corresponds to a bit in memory in the sprite storage range; therefore, 
each sprite requires 63 bytes of storage. The CI 28 has predefined storage locations for 
sprite data in the range 3584 ($0E00) through 4095 ($OFFF). 

The CI 28 graphics system has 8 sprites. Each sprite moves on its own indepen- 
dent plane. A sprite may move in front of or behind objects or other sprites on the 
screen, depending on the specified priority. Standard bit-mapped sprites may be any one 
of the sixteen available colors. Multi-color sprites may have three colors. The colors that I 

are assigned to the pixels within the sprite depend on the bit patterns of the image. In U 

sprite storage memory, the on bits (1) enable the sprite pixels to display the color 
selected by the sprite color register; the off bits (0) disable the corresponding sprite pixels, 
making them transparent and thus allowing the background color to pass through and be 
displayed. Sprites also can be expanded to twice the normal size in both vertical and 
horizontal directions. 

Most of the commercially available graphics software packages for the Commo- 
dore 128 and C64 rely on sprites. For graphics programming applications, sprites offer L 
superior animation capabilities. Single sprites are useful for small moving objects. 
However, you can adjoin and overlay several sprites to give greater detail to animated 
graphic images. For example, suppose you are writing a program that animates a person |_ 
running on the screen. You can make the image of the person as a single sprite, but the 
effect looks much more realistic if you allocate separate sprites for different parts of the 
person's body. The arms can be one sprite, the body another, and the legs a third. Then, 
you can define two additional sprites: one as a second set of legs in a different position, ^ 
and the other as a second set of arms in a different position. Position the first set of 
arms, the body and the first set of legs on the screen so that they are joined into a full 
body. By continually turning on and off the two different sets of arms and legs, the L 
image appears to be running. This process involves overiaying and adjoining sprites. 
The explanation given here is a simplified algorithm, and the actual programming can be 
tricky. Sprite programming has been made easy with the new BASIC 7.0 sprite 
commands. 

The first part of this section explains the new BASIC sprite commands and 
illustrates the procedure for overiaying and adjoining sprites. The second part j 

explains the internal operations of sprites, including storage information, color assign- U 

ments, sprite expansion and addressing the sprite registers in machine language. 
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BASIC 7.0 

SPRITE COMMAND SUMMARY 

Here's a brief description of each BASIC 7.0 sprite command: 



COLLISION: Defines the type of sprite collision on the screen, either sprite to sprite or 
sprite to data collision 

MOVSPR: Positions or moves sprites from one screen location to another 

SPRCOLOR: Defines colors for multi-color sprites 

SPRDEF: Enters sprite definition mode to edit sprites 

SPRITE: Enables, colors, sets sprite screen priorities, and expands a sprite 
J~| SPRSAV: Stores a text string variable into a sprite storage area and vice versa or 

I I copies data from one sprite to another 

SSHAPE: Stores the image of a portion of the bit-map screen into a text-string variable 
-^ 

I BASIC 7.0 

„ SPRITE COMMAND FORMATS 

COLLISION 

n Define sprite collision priorities 

' i where: 



COLLISION type [.statement] 

type Type of collision, as follows: 



1 = Sprite-to-sprite collision 

2 = Sprite-to-display data collision 
f] 3 = Light pen (40 columns only) 



statement BASIC line number of a subroutine 

EXAMPLE: 

COLLISION 1,5000 Detects a sprite-to-sprite collision and program control sent 
to subroutine at line 5000. 

COLLISION 1 Stops interrupt action which was initiated in above example. 

COLLISION 2, 1000 Detects sprite-to-data collision and program control dkected 
to subroutine in line 1000. 

MOVSPR 

Position or move sprite on the screen (using any of the following four formats): 

1. MOVSPR number ,X,Y Place the specified sprite at absolute 

sprite coordinate X,Y. 
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2. MOVSPR number, + X, + Y Move sprite relative to its current 

position. 

3. MOVSPR number, X;Y Move sprite distance x at angle y 

relative to its current position. 

4. MOVSPR number, angle # speed Move sprite at an angle relative to its 

original coordinates, in the clockwise 
direction and at the specified speed. 

where: 

number is sprite's number (1 through 8) 

X,Y> is coordinate of the sprite location. 

ANGLE is the angle (0-360) of motion in the clockwise direction relative to the sprite's 
original coordinate. 

SPEED is the speed (0-15) at which the sprite moves. 

This statement positions a sprite at a specific location on the screen according to 
the SPRITE coordinate plane (not the bit map plane). MOVSPR also initiates sprite 
motion at a specified rate. This chapter contains a diagram of the sprite coordinate 
plane. 
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EXAMPLES: 

MOVSPR 1, 150, 150 



Position sprite 1 at coordinate 150,150. 



MOVSPR 1 , +20, +30 Move sprite 1 to the right 20 (X) coordinates and down 

30 (Y) coordinates. 



MOVSPR 4, 50; 100 
MOVSPR 5, 45 #15 



Move sprite 4 by 50 coordinates at a 100 degree 
angle. 

Move sprite 5 at a 45 degree angle in the clockwise 
direction, relative to its original x and y coordinates. 
The sprite moves at the fastest rate (15). 



NOTE: Once you specify an angle, and a speed in the fourth form of the 
MOVSPR statement, the sprite continues on its path (even if the sprite 
is disabled) after the program stops, until you set the speed to zero (0) 
or press RUN/STOP and RESTORE. 
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SPRCOLOR 

Set multi-color 1 and/or multi-color 2 colors for all sprites 
SPRCOLOR [smcr-1] [,smcr-2] 

where: 
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smcr-l Sets multi-color 1 for all sprites. 
smcr-2 Sets multi-color 2 for all sprites. 

Either of these parameters may be any color from 1 through 16. 

EXAMPLES: 

SPRCOLOR 3,7 Sets sprite multi-color 1 to red and multi-color 2 to blue. 
SPRCOLOR 1,2 Sets sprite multi-color 1 to black and multi-color 2 to white. 

SPRDEF 

Enter the SPRite DEFinition mode to create and edit sprite images. 
SPRDEF 

The SPRDEF command defines sprites interactively. 

Entering the SPRDEF command displays a sprite work area on the screen which is 
24 characters wide by 21 characters tall. Each character position in the grid corresponds 
to a sprite pixel in the displayed sprite to the right of the work area. Here is a summary 
of the SPRite DEFinition mode operations and the keys that perform them: 
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USER INPUT 

1-8 keys 

A 

CRSR keys 

RETURN key 

RETURN key 

HOME key 

CLR key 
1-4 keys 
CTRL key, 1-8 
Commodore key, 1-8 
STOP key 
SHIFT RETURN 

X 
Y 
M 
C 



DESCRIPTION 

Selects a sprite number at the SPRITE NUMBER? prompt only. 

Turns on and off automatic cursor movement. 

Moves cursor. 

Moves cursor to start of next line. 

Exits sprite designer mode at the SPRITE 

NUMBER? prompt only. 

Moves cursor to top left 

corner of sprite work area. 

Erases entire grid. 

Selects color source and enables sprite pixels. 

Selects sprite foreground color (1-8). 

Selects sprite foreground color (9-16). 

Cancels changes and returns to prompt. 

Saves sprite and returns to 

SPRITE NUMBER? prompt. 

Expands sprite in X (horizontal) direction. 

Expands sprite in Y (vertical) direction. 

Multi-color sprite. 

Copies sprite data from one sprite to another. 



This SPRite DEFinition area is shown in Figure 9-1 . 
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Figure 9-1. SPiUte DEFinition Area 

SPRITE CREATION PROCEDURE IN 
SPRITE DEFINITION MODE 

Here's the general procedure to create a sprite in SPRite DEFinition mode: 



1. 



3. 



4. 



Clear the work area by pressing the shift and CLR/HOME keys at the same 
time. 

If you want a multi-color sprite, press the M key and the cursor ( + ) appears 
twice as large as the original one. The double- width cursor appears since 
multi-color mode actually turns on two pixels for every one in standard 
sprite mode. Multi-color sprites have only half the horizontal resolution of 
standard sprites. 

Select a sprite color. For colors between 1 and 8, hold down the CONTROL 
key and press a key between 1 and 8. To select color codes between 9 and 
16, hold down the Commodore (O) key and press a key between 1 and 8. 
Now you are ready to create the shape of your sprite. The numbered keys 1 
through 4 fill the sprite and give it shape. For a single-color sprite, use the 2 
key to fill a character position within the work area. Press the 1 key to erase 
what you have drawn with the 2 key. If you want to fill one character 
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' ' position at a time, press the A key. Now you have to move the cursor 

manually with the cursor keys. If you want the cursor to move automatically 
i"' to the right while you hold it down, press the A key again. As you fill in a 

I i character position within the work area, you can see the corresponding pixel 

in the displayed sprite turn on. The sprite image changes as soon as you edit 
f— , the work area. 

I ! In multi-color mode, the 2 key fills two character positions in the work 

area with the multi-color 1 color, the 3 key fills two character positions with 

the multi-color 2 color. 
n You can turn off (color the pixel in the background color) filled areas 

' within the work area with the 1 key. In multi-color mode, the 1 key turns 

off two character positions at a time. 
r-[ 5. While constructing your sprite, you can move freely in the work area 

without turning on or off any pixels using the RETURN, HOME and cursor 

keys. 

6. At any time, you may expand your sprite in both the vertical and horizontal 
directions. To expand vertically, press the Y key. To expand horizontally, 
press the X key. To return to the normal size sprite display, press the X or Y 
key again. 

When a key turns on AND off the same control, it is referred to as 
toggling, so the X and Y keys toggle the vertical and horizontal expansion of 
the sprite. 

7. When you are finished creating your sprite and are happy with the way it 
looks, save it in memory by holding down the SHIFT key and pressing the 
RETURN key. The Commodore 128 stores the sprites data in the appropri- 
ate sprite storage area. The displayed sprite in the upper right comer of the 
screen is turned off and control is returned to the SPRITE NUMBER 
prompt. If you want to create another sprite enter another sprite number and 
edit the new sprite just as you did with the first one. If you want to display 
the original sprite in the work area again, enter the original sprite number. If 
you want to exit SPRite DEFinition mode, simply press RETURN at the 
SPRITE NUMBER prompt. 

8. You can copy one sprite into another with the O key. 

9. If you do not want to SAVE your sprite, press the STOP key. The Commo- 
dore 128 turns off the displayed sprite and any changes you made are 
cancelled. You are returned to the SPRITE NUMBER prompt. 

10. To EXIT SPRite DEFinition mode, press the RETURN key while the 
SPRITE NUMBER prompt is displayed on the screen without a sprite 
number following it. You can exit under either of the following conditions: 

■ Immediately after you SAVE your sprite in memory (shift RETURN) 

■ Immediately after you press the STOP key 

Once you have created a sprite and have exited SPRite DEFinition mode, your 
sprite data is stored in the appropriate sprite storage area in the Commodore 128's 
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PARAMETER DESCRIPTION 

number Sprite number (1-8) 

on/off Turn sprite on (1) or off (0) 

foreground Sprite foreground color (1-16) 

priority Priority is if sprites appear in front of objects on the screen. Priority 

is 1 if sprites appear in bacic of objects on the screen, 
x-exp Horizontal expansion on (1) or off (0) 

y-exp Vertical expansion on (1) or off (0) 

mode Select standard sprite (0) 

or multi-color sprite (1) 



EXAMPLES: 

SPRITE 1,1,3 Turn on sprite number 1 and color it red. 



u 



memory. Since you are now back in the control of the BASIC language, you have to 
turn on your sprite in order to see it on the screen. To turn it on, use the SPRITE 
command you learned. For example, you created sprite 1 in SPRDEF mode. To turn it 
on in BASIC, color it blue and expand it in both the X and Y directions and enter this 
command: 

SPRITE 1,1,7,0,1,1,0 

Now use the MOVSPR command to move it at a 90-degree angle at a speed of 5, 
as follows: 

MOVSPR 1,90 #5 

Now you know all about SPRDEF mode. First, create the sprite, save the sprite 
data and exit from SPRDEF mode to BASIC. Next, turn on your sprite with the SPRITE 
command. Move it with the MOVSPR command. When you're finished programming, 
SAVE your sprite data in a binary file with the BSAVE command as follows: 

BSAVE "filename", BO, P3584 TO P4096 (This saves all 8 sprites.) 

SPRITE 

Turn on and off, color, expand and set screen priorities for a sprite 

SPRITE number> [,on/ofr][,fngd][,priority] [,x-exp] [,y-exp] [,mode] 

The SPRITE statement controls most of the characteristics of a sprite. The i i 

brackets signify optional parameters. If you omit a parameter, you still must include a | 

comma in its place. 
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Unspecified parameters in subsequent sprite statements take on the characteristics of the 

previous SPRITE statement. You may check the characteristics of a SPRITE with the i I 

RSPRITE function. U 
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SPRITE 2,1,7,1,1,1 



SPRITE 6,1,1,0,0,1,1 



Turn on sprite number 2, color it blue, make it pass behind 
objects on the screen and expand it in the vertical and 
horizontal directions. 

Turn on SPRITE number 6, color it black. The first 
tells the computer to display the sprites in front of objects 
on the screen. The second and the 1 following it tell the 
CI 28 to expand the sprite vertically only. The last 1 
specifies multi-color mode. Use the SPRCOLOR com- 
mand to select the sprite's multi-colors. 
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SPRSAV 

Store sprite data from a text string variable into a sprite storage area or vice versa. 

SPRSAV origin>, destination> 

This command copies a sprite image from a string variable to a sprite storage area. 
It also copies the data from the sprite storage area into a string variable. Either the origin 
or the destination can be a sprite number or a string variable but both cannot be string 
variables. If you are copying a string into a sprite, only the first 63 bytes of data are 
used. The rest are ignored since a sprite can only hold 63 data bytes. 

EXAMPLES: 

SPRSAV 1,A$ Copies the bit pattern from sprite 1 to the string variable A$. 

SPRSAV B$,2 Copies the data from string variable B$ into sprite 2. 

SPRSAV 2,3 Copies the data from sprite 2 to sprite 3. 
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SSHAPE 

Save/retrieve shapes to/from string variables 

SSHAPE and GSHAPE are used to save and load rectangular areas of multi-color 
or bit-mapped screens to/from BASIC string variables. The command to save an area of 
the screen into a string variable is: 



SSHAPE string variable, XI, Yl [,X2,Y2] 



where: 



string variable String name to save data in 

X1,Y1 Comer coordinate (0,0 through 319,199) (scaled) 

X2,Y2 Comer coordinate opposite (XI, Yl) (default is the PC) 



Also see the LOCATE command described in Chapter 3 for information on the 
pixel cursor. 
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EXAMPLES: 

SSHAPE A$, 10, 10 Saves a rectangular area from the coordinates 10, 10 to 

the location of the pixel cursor, into string variable A$. 

SSHAPE B$,20,30 ,47 ,51 Saves a rectangular area from top left coordinate 

(20,30) through bottom right coordinate (47,51) into 
string variable B$. 

SSHAPE D$, + 10, + 10 Saves a rectangular area 10 pixels to the right and 10 

pixels down from the current position of the pixel cursor. 

ADJOINING SPRITES 

The following program is an example of adjoining sprites. The program creates an outer 
space environment. It draws stars, a planet and a spacecraft similar to Apollo. The spacecraft 
is drawn, then stored into two data strings, A$ and B$. The fi-ont of the spaceship, the cap- 
sule, is stored in sprite 1 . The back half of the spaceship, the retro rocket, is stored in 
sprite 2. The spacecraft flies slowly across the screen twice. Since it is traveling so slowly 
and is very far from Earth, it needs to be launched earthward with the retro rockets. After the 
second trip across the screen, the retro rockets fire and propel the capsule safely toward Earth. 
Here's the program listing: 

5 COLOR 4,1: COLOR 0,1: COLOR 1,2: REM SELECT BLACK BORDER & BKGRND, WHITE FRGRD 
10 GRAPHIC 1,1: REM SET HI RES MODE 

17 FOR I=lTO40 

18 X=INT(RND(1)*320)+1:REM DRAW STARS 

19 Y=INT(RND(1)*200)+1:REM DRAW STARS 

21 DRAW 1,X,Y:NEXT :REM DRAW STARS 

22 BOX 0,0,5,70,40,,1:REM CLEAR BOX 

23 BOX 1,1,5,70,40:REM BOX-IN SPACESHIP 

24 COLOR 1,8:CIRCLE 1 , 190, 90 , 35,25:PAINT 1,190,95:REM DRAW & PAINT PLANET 

25 CIRCLE 1,190,90,65,10:CIRCLE 1,190,93,65,10:CIRCLE 1, 190, 95, 65,10 :COLOR 0,1 

26 DRAW 1,10,17 TO 16,17 TO 32,10 TO 33,20 TO 32,30 TO 16,23 TO 10,23 TO 10,17 
28 DRAW 1,19,24 TO 20,21 TO 27,25 TO 26,28:REM BOTTOM WINDOW 

35 DRAW 1,20,19 TO 20,17 TO 29,13 TO 30,18 TO 28,23 TO 20,19:REM TOP WINDOW 

38 PAINT 1,13,20:REM PAINT SPACESHIP 

40 DRAW 1,34,10 TO 36,20 TO 34,30 TO 45,30 TO 46,20 TO 45,10 TO 34,10:REM SPl 

42 DRAW 1,45,10 TO 51,12 TO 57,10 TO 57,17 TO 51,15 TO 46,17iREM ENGl 

43 DRAW 1,46,22 TO 51,24 TO 57,22 TO 57,29 TO 51,27 TO 45,29:REM ENG2 

44 PAINT 1,40,15:PAINT 1 ,47,12:PAINT 1,47,26:DRAW 0,45,30 TO 46,20 TO 45,10 

45 DRAW 0,34,14 TO 44,14 :DRAW 0,34,21 TO 44,21:DRAW 0,34,28 TO 44,28 

47 SSHAPE A$,10,10,33,32:REM SAVE SPRITE IN A$ 

48 SSHAPE BS,34,10,57,32:REM SAVE SPRITE IN B$ 
50 SPRSAV A$,1:REM SPRl DATA 

55 SPRSAV BS,2:REM SPR2 DATA 

60 SPRITE 1,1,3,0,0,0,0:REM SET SPRl ATTRIBUTES 

65 SPRITE 2, 1,7, 0,0, 0,0: REM SET SPR2 ATTRIBUTES 

82 MOVSPR 1,150 ,150:REM ORIGINAL POSITION OF SPRl 

83 MOVSPR 2,172 ,150:REM ORIGINAL POSITION OF SPR2 
85 MOVSPR 1,270 # 5 :REM MOVE SPRl ACROSS SCREEN 
87 MOVSPR 2,270 # 5 :REM MOVE SPR2 ACROSS SCREEN 
90 FOR I=1T0 5950:NEXT!REM DELAY 

92 MOVSPR 1,150,150:REM POSITION SPRl FOR RETRO ROCKET LAUNCH 

93 MOVSPR 2,174,150:REM POSITION SPR2 FOR RETRO ROCKET LAUNCH 

95 MOVSPR 1,270 # 10 :REM SPLIT ROCKET 

96 MOVSPR 2, 90 # 5 :REM SPLIT ROCKET 

97 FOR I=1T0 1200:NEXT:REM DELAY 

98 SPRITE 2,0:REM TURN OFF RETRO ROCKET (SPR2) 

99 FOR I=1T0 20500:NEXT:REM DELAY 

100 GRAPHIC 0,1:REM RETURN TO TEXT MODE 
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Here's an explanation of the program: 



Line 5 COLORs the background black and the foreground white. 
Line 10 selects standard bit map mode and clears the bit map screen. 
Lines 17 through 21 DRAW the stars. 

Line 23 BOXes in a display area for the picture of the spacecraft in the top-left 
comer of the screen. 
^ Line 24 DRAWs and PAINTs the planet. 

j ! Line 25 DRAWs the CIRCLEs around the planet. 

' Line 26 DRAWs the outline of the capsule portion of the spacecraft. 

Line 28 DRAWs the bottom window of the space capsule. 
P Line 35 DRAWs the top window of the space capsule. 

i i Line 38 PAINTs the space capsule white. 

Line 40 DRAWs the outline of the retro rocket portion of the spacecraft. 
p Line 42 and 43 DRAW the retro rocket engines on the back of the spacecraft. 

I I Line 44 PAINTs the retro rocket engines and DRAWs an outline of the back of the retro 

rocket in the background color. 
Line 45 DRAWs lines on the retro rocket portion of the spacecraft in the background 
j I color. (At this point, you have displayed only pictures on the screen. You have 

' I not used any sprite statements, so your rocketship is not yet a sprite.) 

Line 47 positions the SSHAPE coordinates above the first half (24 by 21 pixels) of the 
n capsule of the spacecraft and stores it in a data string, A$. 

) I Line 48 positions the SSHAPE coordinates above the second half (24 by 21 pixels) of 

the spacecraft and stores it in a data string, B$. 
r-i Line 50 transfers the data from A$ into sprite 1 . 

j Line 55 transfers the data from B$ into sprite 2. 

Line 60 turns on sprite 1 and colors it red. 
_« Line 65 turns on sprite 2 and colors it blue. 

j I Line 82 positions sprite 1 at coordinate 150,150. 

Line 83 positions sprite 2, 23 pixels to the right of the starting coordinate of 
sprite 1. 
j I Lines 82 and 83 actually join the two sprites. 

'■ ^ Lines 85 and 87 move the joined sprites across the screen. 

Line 90 delays the program. This time, delay is necessary for the sprites to complete the 
n two trips across the screen. If you leave out the delay, the sprites do not have 

I enough time to move across the screen. 

Lines 92 and 93 position the sprites in the center of the screen, and prepare the 
p spacecraft to fire the retro rockets. 

! I Line 95 propels sprite 1 , the space capsule, forward. The number 10 in line 95 specifies 

the speed in which the sprite moves. The speed ranges from (stop ) to 15 
— (fastest). 

j Line 96 moves the expired retro rocket portion of the spacecraft backward and off the 

screen. 
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Line 97 is another time delay so the retro rocket, sprite 2, has time to move off 

the screen. 
Line 98 turns off sprite 2, once it is off the screen. 

Line 99 is another delay so the capsule can continue to move across the screen. 
Line 100 returns you to text mode. 



SPRITE PROGRAM EXAMPLES 

The best way to create sprites is with SPRDEF. The following examples assume you 
have created your sprites in SPRDEF mode. 

The first example sprite program illustrates the use of the SPRITE and MOVSPR 
commands. It positions all eight sprites so they appear to converge on one screen 
location, then scatter in all eight directions. Here's the listing: 

10 REM MOVE SPRITE EXAMPLE 

20 FOR 1=1 TO 8 

30 MOVSPR 1,100,100 

40 NEXT 

50 FOR 1=1 TO 8 

60 SPRITE 1,1,1,1,1,1,0 

70 MOVSPR 1,1*30 # I 

80 NEXT 

Lines 20 through 40 place all eight sprites at sprite coordinate location 100,100. 
At this point, the sprites are not yet enabled, but when they are, all eight are on top of 
one another. 

Lines 50 and 60 turn on each of the eight sprites in eight different colors. The first i' / 

"I" is the sprite number parameter. The first "1" in line 60 signifies the enabling of [J 

each sprite. The second "I" specifies the color code for each sprite. The second "1" 
(the fourth parameter) sets the display priority for all the sprites. A display priority of , , 

one tells the C128 to display the sprites behind objects on the screen. A zero display 
priority enables sprites to pass in front of objects on the text or bit-map screen. The fifth 
and sixth parameters, both of which are ones (1), expand the sprites' size in both the 
vertical and horizontal directions to twice their original size. The final parameter in the 
SPRITE statement selects the graphics display mode for the sprites; either standard U 

bit-map sprites (0) or muUi-color bit-map sprites (1). In this example, the sprites are 
displayed as standard bit-map sprites. 

Line 70 moves the sprites on the screen. The first parameter, I, represents the 
sprite number. The second parameter, "1*30", defines the angle at which the sprites 
travel on the screen. The pound sign (#) notation signifies that the sprites move 
according to a particular angle and speed. The final parameter "I" specifies the speed at 
which the sprites travel on the screen. In this example, sprite 1 moves at the slowest rate 
of 1 , sprite 2 moves at the next highest speed of 2, while sprite 8 moves the fastest of 
the eight sprites at speed 8. The highest speed a sprite can move is 15. 

Finally, line 80 completes the FOR . . . NEXT structure of the loop. 
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Notice that the sprites move continuously even after the program has stopped 
RUNning. The reason for this is that sprites are wedged into the interrupt processing of 
the CI 28. To turn off and stop the sprites on the screen, either issue a SPRITE 
command that turns them off, or press RUN/STOP and RESTORE. 

The second sprite program example provides a simplified adjoining sprite algo- 
rithm. It moves two adjoined sprites across the screen at a ninety-degree angle, 
assuming that your sprites already reside in the sprite storage range between 3584 
($0E00) and 4095 ($OFFF). For simplicity, if you don't have any actual sprite images 
stored in the sprite data area, fill the sprite data area with 255 ($FF) from within the 
Machine Language Monitor with this command: 



F OEOO OFFF FF 

n For now, this command turns on all pixels within each sprite. Now you can see 

) I how the adjoining algorithm places and moves sprites 7 and 8 side by side. 

Here's the listing: 

r^ 10 REM ADJOINING SPRITE ALGORITHM 

' I 20 REM THIS PROGRAM ASSUMES YOUR SPRITES ALREADY EXIST IN SPRITE STORAGE 

I I 30 1=1 iREM INITIALIZE DISTANCE I 

35 SCNCLR 

40 MOVSPR 8,50,100:REM SET GRIG POSITION OF SPRITE 8 
f^ 50 MOVSPR 7,73,100:REM SET ORIG POSITION OF SPRITE 7 TO ADJOIN SPR 8 

I 60 DO 

I 70 SPRITE 8, 1,3: REM ENABLE SPR 8 

80 SPRITE 7,1,4:REM ENABLE SPR 7 

90 MOVSPR 8,1 ;90:REM MOVE SPR 8 I UNITS AT A 90 DEGREE ANGLE 

100 MOVSPR 7,1 ;90:REM MOVE SPR 8 I UNITS AT A 90 DEGREE ANGLE 
I 110 1=1+1 ;REM INCREMENT LOOP 

I 120 LOOP 

Line 30 initializes the distance variable I to 1. 
p Line 40 positions sprite 8 at absolute coordinates 50,100. Since this program 

j I moves two adjoining sprites from the left to right at a ninety-degree angle, sprite 7, 

which is attached to sprite 8 must be positioned in such a way that it is touching the right 
^ edge of sprite 8. Line 50 places sprite 7 on the exact right edge of sprite 8. Since a sprite 

j is 24 pixels wide (before expansion), to adjoin two sprites together, place the ajoining 

sprite exactly 24 pixels to the right of the top left comer coordinate position of sprite 8. 

The position of a sprite is placed on the sprite coordinate plane according to the upper 
I j leftmost pixel of the sprite. Since the original position of sprite 8 is 50,100, add 24 

! * (inclusive) to the X (horizontal) coordinate to make them join exactly on the respective 

edges of both sprites. This is provided your sprites are exactly 24 pixels wide. If you 
p don't fill the entire dimensions of a sprite, you may have to adjust the coordinates so 

I [ that they meet correctly. 

At this point, the sprite coordinates are perfectly adjoined. Line 60 initiates a loop, 
p so that the distance can be updated to enable the sprites' movement across the screen. 

) j Lines 70 and 80 enable sprites 8 and 7 and color them red and cyan, respectively. 

Lines 90 and 100 move sprite 8 and 7, respectively, at a 90-degree angle 

according to the distance specified by the variable I. Line 110 updates the distance of 1 
j I each cycle through the loop. Line 120 circulates the loop until the distance variable I is 

' ' equal to 320. 
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The third sprite example provides an algorithm to overlay two sprites and move U 

them on the screen on a 45-degree angle. Again, this program assumes your sprite data 
resides in sprite storage. If your sprite images are not stored there, fill the sprites with T"] 

data as you did in the last adjoining example. ! I 

Here's the listing: 
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10 REM OVERLAY EXAMPLE 

20 REM THIS PROGRAM ASSUMES SPRITE DATA RESIDES IN SPRITE STORAGE 

30 1=1 :REM INITIALIZE DISTANCE I 

35 SCNCLR 

40 MOVSPR 8,50,100:REM SET ORIG POSITION OF SPRITE 8 

50 MOVSPR 7,50,100:REM SET ORIG POSITION OF SPRITE 7 TO OVERLAY SPR 8 

60 DO 

70 SPRITE 8,1,3 :REM ENABLE SPR 8 

80 MOVSPR 8,1 ;45 :REM MOVE SPR 8 I UNITS AT A 45 DEGREE ANGLE 

90 SPRITE 8,0,3 :REM TURN OFF SPR8 

100 SPRITE 7,1,4 :REM ENABLE SPR 7 i~( 

110 MOVSPR 7, I; 4 5 :REM MOVE SPR 8 I UNITS AT A 45 DEGREE ANGLE 

120 SPRITE 7,0,3 :REM TURN OFF SPR 7 M 

140 LOOP 

As in the last program, line 30 initializes the distance variable I to 1. | ! 

Lines 40 and 50 position sprites 8 and 7, respectively, at coordinate 50,100. At Lj 

this point the sprites are not yet enabled, but when they are, sprite 7 will overlay sprite 8 
since the lower sprite number has display priority over the higher sprite number. 

Line 60 initiates a DO loop to move the sprites along the sprite coordinate plane. 

Line 70 enables sprite 8 and colors it red. Line 80 moves sprite 8 a distance of one 
coordinate according to the current value of L Line 90 disables sprite 8. 

Lines 100 through 120 perform the same operations for sprite 7 as lines 70 through i | 

90 did for sprite 8: enable, move a single distance coordinate according to I and disable. ^ 

Line 140 repeats the process. 

Since this process is repeated so quickly, it appears as though the two sprites 
alternate movements. When you create the actual images you will use in your overlay 
sprite program, the images between which you alternate will be ones that simulate the 
movement of two images and create one animated image. r 

Create two sprites that appear to form a single animated image. You may have to 
perfect the timing of the enabling and disabling of the images to make the animated 
image appear more smooth. Nonetheless, you have a basis for animating two objects 
into one single moving object. | j 

t-j 

Although these program examples are vratten in BASIC, the algorithms are the 
same whether you are programming in BASIC or machine language. The next section [ / 

discusses sprite operations independent of the BASIC language. Since this section J_ 

explained sprites according to BASIC, the next section elaborates on the inner workings 
of sprites from a machine level (language) perspective. 
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THE INNER WORKINGS OF SPRITES 

) \ You have seen how to create, move, color and expand sprites with the BASIC 7.0 sprite 

commands. This section explains how to control sprites outside of the BASIC sprite 
'— t commands (except SPRDEF). This tells you which VIC registers are affected and the 

j j specific bits that must be set or cleared to manipulate the sprite features. 

Registers of the VIC chip control all aspects of sprites. The enabling of specific 
^ bits in certain VIC registers turns on the features of the eight available sprites. The order 

I i in which you turn on these features is critical to sprite animation. Following is a 

' * summary of the steps necessary to display, color, move and expand sprites. Next to each 

step is the VIC chip register or other memory location involved in each element of sprite 
'"I programming. 



SPRITE PROGRAMMING SEQUENCE REGISTERS INVOLVED 



1. Create the sprite image Sprite Data Storage: 3584-4095 ($OE0O-$OFFF) 

' ' This is also programmable. You must change the sprite 

pointer values. 

j 2. Point to the sprite data Sprite Data Pointers: 2040-2047 ($07F8-$07FF), or 

' 8184-8191 ($1FF8-$1FFF) when the bit map screen has 

been cleared with GRAPHIC 1,1 

rj 3. Enable (turn on) the sprite 53269 ($D015) (bits 7-0, depending on sprite number) 

4. Color the sprite Standard 53287-53294 ($D027-$D02E) 

Multi-color 53276 ($D01C), 53285 ($D025), 53286 ($D026) 

5. Position the sprite 53248-53264 ($D000-$D010) 

6. Expand the sprite 53271 ($D017) (Y direction), 53277 ($D01D) (X direction) 

7. Define sprite display priorities 53275 ($D01B) 

8. Define sprite collision priorities 53278 ($D01E), 53279 ($D01F) 

These registers control most sprite characteristics. Once you learn these programming 
steps, you will be able to exercise full control over the display and movement of sprites. 

CREATING THE SPRITE IMAGE 

An easy way to create sprites on the CI 28 is through SPRite DEFinition mode 
(SPRDEF). For an explanation of SPRDEF see the SPRDEF entry in the beginning of 
this chapter. This section assumes your sprite image is already created, and it resides in 
the sprite data storage area. Before leaving SPRDEF, remember to press the SHIFT key 
and RETURN at the same time; this allows SPRDEF to store the sprite data in the sprite 
data storage area. Press RETURN a second time to exit SPRDEF. 

The Commodore 128 has a dedicated portion of memory ranging from decimal 
address 3584 ($0E00) through 4095 ($OFFF), where sprite data is stored. This portion of 
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memory takes up 512 bytes. As you know, a sprite is 24 pixels wide by 21 pixels tall. In 
standard sprites, each pixel corresponds to one bit in memory. If the bit in a sprite is off 
(equal to 0), the corresponding pixel on the screen is transparent, which allows the 
background to pass through the sprite. If a bit within a sprite is on (equal to 1), the 
corresponding pixel on the screen is turned on in the foreground color as determined by 
the sprite color registers. The combination of zeroes and ones produces the image you 
see on the screen. Multi-color sprites assign colors differently. See the multi-color sprite 
section later in this chapter for details. 

Since a sprite is 24 by 21 pixels and each pixel is represented by one bit of storage 
in memory, one sprite uses up 63 bytes of memory. See Figure 9-2 to understand the 
storage requirements for a sprite's data. 



12345678 12345678 12345678 

1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 

21 

Each Row = 24 bits = 3 bytes 

Figure 9-2. Sprite Data Requirements 



A sprite requires 63 bytes of data. Each sprite block is actually made up of 64 
bytes; the extra byte is not used. Since the Commodore 128 has eight sprites and each 
one consists of a 64-byte sprite block, the computer needs 512 (8x64) bytes to 
represent the data of all eight sprite images. 

The area where all eight sprite blocks reside starts at memory location 3584 
($0E00) and ends at location 4095 ($OFFF). Figure 9-3 lists the memory address ranges 
where each individual sprite stores its data. 



u 



n 








Q 



! \ 



SPRITES 281 



I I 



I I 

I! 



/ i 



$OFFF (4095 Decimal) 

]— Sprite 8 
$OFCO 

]— Sprite 7 
$0F80 

}— Sprite 6 
$0F40 

]— Sprite 5 
$0F00 

]— Sprite 4 
$OECO 

]— Sprite 3 
$0E80 

]— Sprite 2 
$0E40 

]— Sprite 1 
$0E00 (3584 Decimal) 



Figure 9-3. Memory Address Ranges for Sprite Storage 



Keep in mind that sprites are referred to as 1 through 8 in BASIC, but through 7 
in machine language. 

n SPRITE POINTERS 

) i 

The VIC chip needs to know where to look for the bit patterns (data) that make up the 

sprite image in memory. The sprite pointers are used explicitly for this purpose. 
j j Unlike the Commodore 64, the CI 28 has automatically filled the sprite data 

I \ pointers with values that direct the VIC chip to point to the data stored in the sprite data 

range 3584 ($0E00) through 4095 ($OFFF). These sprite data pointers are located at 
f-t 2040 ($07F8) through 2047 ($07FF) for sprites and 7 respectively. They are also located 

j I in the address range 8184 ($1FF8) through 8191 ($1FFF), once the bit map screen is 

cleared with the GRAPHIC 1,1 command. The default contents of these locations are: 

-^ Hexadecimal 38 39 3A 3B 3C 3D 3E 3F 

j i Decimal 56 57 58 59 60 61 62 63 

To find the actual location where the sprite data pointers are looking for data in 
^^ memory, multiply the contents of the sprite data pointer by 64 (decimal). By multiplying 

j j these values, you'll see that the pointers look for data in the default sprite storage 

locations in Figure 9-3. See Figure 9-4 for an illustration. 

The way the Commodore 128 automatically points to the correct sprite data is conven- 
ient for progranuning, since it eliminates a step (provided the original values of the sprite 
pointers have not been modified). If you want to store sprite data somewhere else in 
memory, however, you'll have to change the original value of the sprite pointer (from 
location 2040 through 2047, or 6184 through 8191) to a value that is equal to: 

Start of Sprite Data / 64 = new contents of sprite pointer 
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DATA POINTER 




START OF 




CONTENTS** 




SPRITE DATA 




Sprite Data Pointer = 56 




* 


64 = 3584 ($0E00) 


_ 


Sprite 1 Data Pointer = 57 




* 


64 = 3648 ($0E40) 


Sprite 2 Data Pointer = 58 




* 


64 = 3712 ($0E80) 




Sprite 3 Data Pointer = 59 




♦ 


64 = 3776 ($OECO) 


1^^ 


Sprite 4 Data Pointer = 60 




* 


64 = 3840 ($0F00) 


Sprite 5 Data Pointer = 61 




« 


64 = 3904 ($0F40) 




Sprite 6 Data Pointer = 62 




* 


64 = 3968 ($0F80) 




Sprite 7 Data Pointer = 63 




* 


64 = 4032 ($OFCO) 




** = This applies to video bank 


only. 







Figure 9-4. Sprite Data Locations 



The start of sprite data is divided by 64 because the data area is allocated in 64-byte 

sections. For example, you want to place your sprite data in the new location 6144 \ i 

($1800). Divide 6144 by 64 to get 96. Place the value 96 ($60) in address 2040 ($078F). Ij 



ENABLING A SPRITE 



LDA #$20 
STA $D015 

To enable sprites 5 and 7, raise two to the fifth (32 ($20)) and add it to two to the 
seventh (128($80)) to obtain the result 160 ($A0): 

LDA SAO 
STA $D015 






Once the sprite image has been defined, and the data pointer is pointing to the correct 
data, you can turn on the sprite. You do this by placing a value in the Sprite Enable 
Register, location 53269 ($D015). The value placed in this register depends on which 
sprite(s) you want to turn on. Bits through 7 correspond to sprites through 7. To 
enable sprite 0, set bit 0. To enable sprite 1, set bit 1 and so on. The value you 
place in the sprite enable register is equal to two raised to the bit position in decimal. j I 

If you are programming in machine language and want to enable more than one Ij 

sprite at a time, add the values of two raised to the bit positions together and store the 
result in the sprite enable register. For example, to enable sprite 5, raise two to the fifth [ / 

power (32 ($20)) and store it as follows: 



LJ 
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An easier way of perceiving the idea is through binary notation in the Machine 
Language Monitor as follows: j I 

LDA # % 10100000 
STA $D015 

To disable the sprite display, clear the bits in the sprite enable register. 
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ASSIGNING COLOR TO SPRITES 

Sprites have two kinds of color displays: standard bit-map and multi-color bit-map 
sprites. The color assignments to the pixels within the sprites work in a similar way to 
standard bit-map and multi-color bit-map modes for the screen. 
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STANDARD BIT-MAP SPRITES 

Standard bit-map sprites each have their own color register. The lower four bits of each 
sprite color register determine the sprite color as specified by the sixteen CI 28 color 
codes. Figure 9-5 shows the standard bit-map sprite color registers. 
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ADDRESS 

53287 ($D027) 

53288 ($D028) 

53289 ($D029) 

53290 ($D02A) 

53291 ($D02B) 

53292 ($D02C) 

53293 ($D02D) 

53294 ($D02E) 



DESCRIPTION 

SPRITE COLOR 
SPRITE 1 COLOR 
SPRITE 2 COLOR 
SPRITE 3 COLOR 
SPRITE 4 COLOR 
SPRITE 5 COLOR 
SPRITE 6 COLOR 
SPRITE 7 COLOR 



REGISTER 
REGISTER 
REGISTER 
REGISTER 
REGISTER 
REGISTER 
REGISTER 
REGISTER 



Figure 9-S. Standard Bit Map Sprite Color Registers 
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Figure 9-6 lists the color codes that are placed in the standard bit-map sprite color 
registers: 






Black 


8 


Orange 


1 


White 


9 


Brown 


2 


Red 


10 


Light Red 


3 


Cyan 


11 


Dark Gray 


4 


Purple 


12 


Medium Gray 


5 


Green 


13 


Light Green 


6 


Blue 


14 


Light Blue 


7 


Yellow 


IS 


Light Gray 



Figure 9-6. Sprite Color Codes 



In standard bit-map sprites, the data in the sprite block determine how the colors 
are assigned to the pixels on the screen within the visible sprite. If the bit in the 
sprite storage block is equal to 1, the corresponding pixel on the screen is assigned 
the color from the standard sprite color register. If the bit in the sprite data block 
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is equal to zero, those pixels on the sprite are transparent and the background data 
from the screen passes through the sprite. 



ADDRESS 



BIT PAIR DESCRIPTION 

00 TRANSPARENT (SCREEN COLOR) 

01 SPRITE MULTI-COLOR REGISTER #0 (53285) ($D025) 

10 SPRITE COLOR REGISTER 

11 SPRITE MULTI-COLOR REGISTER #1 (53286) ($D026) 



u 



MULTI-COLOR SPRITES jj 

Multi-color sprites offer a degree of freedom in the use of color, but you trade the 

higher resolution of standard sprites for the added color. Multi-color sprites are displayed 

in three colors plus a background color. Multi-color bit-map sprites are assigned colors j j 

similar to the way the other multi-color modes work. Before you can assign a sprite ^ 

multiple colors, you must first enable the multi-color sprite. The sprite multi-color 

register in location 53276 ($D01C) operates in the same manner as the sprite enable | ! 

register. Bits through 7 pertain to sprites through 7. To select a multi-color sprite, J 

set the bit number that corresponds to the sprite number. This requires that you raise 

two to the bit position of the sprite that you want displayed in multi-color. For example, ) / 

to select sprite 4 as a multi-color sprite, raise two to the fourth power (16) and place j_] 

it in the multi-color sprite register. In machine language, perform the following 

instructions: , i 

LDA #$10 J 

STA $D01C 



To select more than one multi-color sprite, add the values of two raised to the bit 
positions together and store the value in the multi-color sprite register. 

The VIC chip provides two multi-color registers (0 and 1), in which to place color 
codes. These are the locations of the sprite multi-color registers: | 



u 

] i 
L) 



Sprite Multi-Color Register 53285 ($D025) U 

Sprite Multi-Color Register 1 53286 ($D026) 

] I 
The color codes are those listed in Figure 9-6. { | 



y 



Like multi-color character mode, the pixels in the multi-color sprites are assigned 
color according to the bit patterns in the sprite storage block. In this mode, the bits in 
the sprite block are grouped in pairs. The bit pair determines how the pixels are assigned 
their individual colors, as follows: j / 
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If the bit pair is equal to 00, the pixels are transparent and the background from 
the screen passes through the sprite. If the bit pattern equals 10 (binary), the color is 
taken from the sprite color register (locations 53287-53294) of the sprite being defined. 
Otherwise, the other two bit pair possibilities (01 and 11) are taken from sprite 
multi-color registers and 1 respectively. 
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POSITIONING SPRITES ON THE SCREEN 

Each sprite has two position registers to control the sprite's position on the visible screen: 
horizontal (X coordinate) and vertical (Y coordinate) positions. Figure 9-7 gives the 
memory locations of the sprite position registers as they appear in the C128 memory. 



LOCATION 
DECIMAL HEX 



DESCRIPTION 



n 



1 1 



n 



53248 


($D000) 


SPRITE 


53249 


($D001) 


SPRITE 


53250 


($D002) 


SPRITE 


53251 


($D003) 


SPRITE 


53252 


($D004) 


SPRITE 


53253 


($D005) 


SPRITE 


53254 


($D006) 


SPRITE 


53255 


($D007) 


SPRITE 


53256 


($D008) 


SPRITE 


53257 


($D009) 


SPRITE 


53258 


($DOOA) 


SPRITE 


53259 


($DOOB) 


SPRITE 


53260 


($DOOC) 


SPRITE 


53261 


($DOOD) 


SPRITE 


53262 


($DOOE) 


SPRITE 


53263 


($DOOF) 


SPRITE 


53264 


($D010) 


SPRITE 



X POSITION REGISTER 

Y POSITION REGISTER 

1 X POSITION REGISTER 

1 Y POSITION REGISTER 

2 X POSITION REGISTER 

2 Y POSITION REGISTER 

3 X POSITION REGISTER 

3 Y POSITION REGISTER 

4 X POSITION REGISTER 

4 Y POSITION REGISTER 

5 X POSITION REGISTER 

5 Y POSITION REGISTER 

6 X POSITION REGISTER 

6 Y POSITION REGISTER 

7 X POSITION REGISTER 
7 Y POSITION REGISTER 
X MSB REGISTER 



Figure 9-7. Memory Location of Sprite Position Register 



The sprite position registers together plot the sprite on a vertical and horizontal 
coordinate. The position of reference for the calculated vertical and horizontal coordi- 
nate is taken from the upper-left comer pixel within the sprite. Whenever you want to 
place the sprite on a particular screen position, calculate the position using the upper left 
comer pixel within the sprite. The sprite coordinate plane is not the same as the bit-map 
coordinate plane. The bit-map coordinate plane starts in the upper-left comer of the 
screen at coordinate 0,0. The lower right comer of the bit map coordinate plane is point 
319,199. The sprite coordinate plane starts at point 24,50 in the top-left comer of the 
visible screen. The final visible point on the sprite coordinate plane at the bottom-right 
comer of the screen is 343,249. Figure 9-8 shows how the sprite coordinate plane 
relates to the visible screen. 
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(SOO) 24 ($18) 



296 ($126) 
I 



29 (»10) ' i 

50 (S32) 1 



208 ($D0)- 



250 ((FA)- 




VISIBLE VIEWING AREA 



NTSC* 

40 COLUMNS 

25 ROWS 




8 (SOS) 



--50 (S32) 



229 (ses) 

250 (SFA) 



I 



I 



488 (S1ES) 24 (SIS) 



I 

I 
I I 
I I 
320 ($140) 344 (S1S8) 



'North American television tfansmission standards lor your tiome TV. 



Figure 9-8. Visible Sprite Coordinates 
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After seeing the sprite coordinate plane, you may have noticed something unusual. 
The vertical coordinate positions have a range of 200. The horizontal coordinate 
positions have a range of 320 coordinates. Since the CI 28 is an 8-bit computer, the 
highest value any register can represent is 255. 

How do you position a sprite past the 255th horizontal screen position? The 
answer is, you have to borrow a bit from another register in order to represent a value 
greater than 255. 

An extra bit is already set aside in the Commodore 128 memory in case you want 
to move a sprite past the 255th horizontal coordinate. Location 53264 controls sprite 
movement past position 255. Each of the 8 bits in 53264 controls a sprite. Bit controls 
sprite 0, bit 1 controls sprite 1 and so on. For example, if bit 7 is set, sprite 7 can move 
past the 255th horizontd position. 

Each time you want a sprite to move across the entire screen, turn on the borrowed 
bit in location 53264 when the sprite reaches horizontal position 255. Once the sprite 
moves off the right edge of the screen, turn off the borrowed bit-so the sprite can move 
back onto the left edge of the screen. The following commands allow sprite seven to 
move past the 255th horizontal position: 
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LDA $D010 
ORA #$80 
7 STA $D010 

The number 128 is the resulting decimal value from setting bit 7. You arrive at this 

value by raising two to the seventh power. If you want to enable bit 5, raise two to the 

7 fifth power, which, of course, is 32. The general rule is to raise two to the power of the 

i sprite number that you want to move past the 255th horizontal screen position. Now you 

can borrow the extra bit you need to move a sprite all the way across the screen. To 

-J allow the sprite to reappear on the left side of the screen, turn off bit seven again, as 

follows: 



LDA $D010 
AND #$7F 
STA $D010 



Not all of the horizontal (X) and vertical (Y) positions are visible on the screen. 
p Only vertical positions 50 through 249 and horizontal positions 24 through 343 are 

i I visible. Location 0,0 is off the screen as is any horizontal location less than 24 and 

greater than 343. Any vertical location less than 50 and greater than 249 is also off the 
p, screen. The off-screen locations are set aside so that an animated image can move 

j 1 smoothly on and off the screen. 



EXPANDING THE SIZE OF SPRITES 



I \ The VIC chip offers a feature that allows sprites to be expanded in size, in both the 

horizontal and vertical directions. When the sprite is expanded, the sprite resolution 

r-' does not increase, the pixels within the sprite just cover twice as much area; therefore, 

the sprite is twice as large. Here are the locations in memory for vertical and horizontal 
sprite expansion: 



ADDRESS 



Vertical (Y) Sprite Expansion Register 53271 ($D017) 

Horizontal (X) Sprite Expansion Register 53277 ($D01D) 



These registers operate in the same manner as the sprite enable register. 
Bits through 7 pertain to sprites through 7. To expand the sprite size in either 
direction, raise two to the bit position and place it in the expansion register(s). For 
example, to expand sprite 7 in both directions, perform these machine language 
instructions: 

LDA #$80 (% 10000000 = binary notation in the Monitor) 
STA $D017 
STA $D01D 
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To expand more than one sprite, add two raised to the bit position for the sprite 
numbers you want to expand, and store the result in the expansion registers. 

To return the sprites to their original size, clear the bits in the expansion 
registers. 

SPRITE DISPLAY PRIORITIES 

In your sprite programs, you have the option of displaying sprites in front of or behind 
other sprites or objects on the screen. This is known as defming the sprite's display 
priorities. The VIC chip defines two distinct sprite display priorities: 

1 . Sprite-to-sprite 

2. Sprite-to-data 

SPRITE-TO-SPRITE DISPLAY PRIORITIES 

Each of the eight sprites available on the Commodore 128 is assigned its own plane in 
which it moves independent of other sprites or of the pictures on the screen background. 
Visualize the sprite planes as in Figure 9-9. 
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Sprite plane 7 

Sprite plane 6 
Sprite plane 5 

Sprite plane 4 
Sprite plane 3 

Sprite plane 2 



Sprite plane 1 
Sprite plane 

Figure 9-9. Relationship of Sprite Planes 
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The display priority of each sprite plane depends on the sprite number. The 
sprite-to-sprite display priorities are predefined according to the sprite number. This 
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feature is preset by the CI 28 hardware, and is not controlled through a software 
register. The lower the sprite number, the higher the priority. The higher priority sprite 
passes in front of the lower priority sprite. Sprite has the highest priority; therefore, it 
passes in front of any other sprites that may be on the screen should they meet at a 
particular screen location. For example, sprites 1 and 5 are moving toward a common 
location on the screen. When the sprites reach the common location, sprite 1 passes in 
front of sprite 5, since the lower sprite number has the higher display priority. Keep this 
in mind when you want sprites to intersect paths and pass behind or in front of one 
another. This is important when overlaying sprites. Assign the sprite you want to pass in 
front of other sprites to the lower sprite number. 

Portions of sprites (pixels) that are not assigned color (the bits in the sprite storage 
block corresponding to those pixels are equal to zero) are transparent. Holes in these 
sprites allow background data to pass through the transparent area and create a "win- 
dow" effect. The same window effect occurs when a higher priority sprite with "holes" 
passes in front of a lower priority sprite. Even though one sprite has a higher priority, 
f-^ if portions of that higher priority sprite are transparent, the lower priority sprite or 

the background display data is allowed to pass through the higher priority sprite. 



SPRITE-TO-DATA DISPLAY PRIORITIES 

The sprite to data (background screen) priority is selected through a software register 
within the VIC chip. The Sprite to Background Display Priority Register (location 
53275 ($D01B)) specifies whether a sprite passes in front of or behind the objects on the 
screen background plane. This feature makes sprites seem more realistic. The default 
value of this register is zero; therefore, all sprites pass in front of objects on the screen 
background unless you change the bit values in this register. In other words, upon 
power-up, all sprites have a higher priority than the screen background. 

Bits through 7 pertain to sprites through 7. If a bit in this register is set, 
the sprite passes behind the objects on the screen background. The bit number corre- 
spondence to the sprite number works the same way as the sprite enable register and 
many of the other sprite registers. To set these bits, raise two to the power of the bit 
position for the sprite number that you want to pass behind the screen background 
objects. For instance, to cause sprite 6 to pass behind objects on the screen background, 
raise 2 to the sixth power and place the hexadecimal equivalent in location 53275 
($D01B) in machine language as follows: 

LDA #$40 (%01(K)0000 = binary rotation in the Monitor) 
STA $D01B 

To set the sprite-to-data display priorities for more than one sprite, add the values 
together for two raised to the respective bit positions and store the result in location 
53275 ($D01B). 

SPRITE COLLISION PRIORITIES 

The VIC chip has a feature that enables you to detect when a collision occurs between 
sprites, or between a sprite and screen objects. 
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SPRITE-TO-SPRITE COLLISIONS '^ 

A sprite-to-sprite collision occurs when an enabled pixel in the foreground of one sprite 

overlaps an enabled pixel from the foreground of another sprite at any point on the sprite ] j 

coordinate plane. The collision may also occur at an off-screen coordinate location. "-^ 

Location 53278 ($D01E) flags whether a sprite-to-sprite collision has occurred. This 

register, like most of the sprite registers, has a bit which detects a collision for each | i 

sprite. Bits through 7 pertain to sprites through 7. If a sprite is involved in a |_1 

sprite-to-sprite collision, the bit corresponding to the sprite involved in the collision is 

set; therefore, at least two bits are always set in a sprite-to-sprite collision. These bits > ; 

remain set until they are read at which time the VIC clears the register. You should store ) \ 

the value of this register in a variable until the collision or conditional code depending 

on the collision is fully processed. 

Once a sprite-to-sprite collision is detected, the sprite-to-sprite collision Interrupt 
Request (IRQ) flag, bit 2 of location 53273 ($D019), is set and an interrupt occurs if 
enabled in the IRQ Mask Register at 53274 ($D01A). When this occurs, you can 
incorporate an interrupt routine to be activated upon the collision of two sprites. \ 

Therefore, your sprite-to-sprite collision interrupt routine is only executed upon the 
condition that two sprites collide. This built-in feature gives you a way to conditionally 
wedge an interrupt (IRQ) routine into your application program, depending on the 
behavior of the sprites on the screen. ! 

U 

SPRITE-TO-DATA COLLISIONS 

A sprite-to-data collision occurs when an enabled pixel in the foreground of a sprite 
overiaps a pixel from the foreground of an object on the screen. Location 53279 
($D01F) flags whether a sprite-to-data collision has occurred. This register has a bit 
which detects a collision for each sprite. Bits through 7 pertain to sprites through 7. 
If a sprite is involved in a sprite-to-data collision, the bit corresponding to the sprite 
involved in the collision is set. These bits remain set until they are read at which time 
the VIC chip clears the entire register. A recommended programming practice is to store 
the value of this register in a variable until the collision or conditional code depending 
on the collision is fully processed. 

Once a sprite-to-data collision is detected, the sprite-to-data collision IRQ flag in 
bit 1 of location 53273 ($D019) is set and an interrupt occurs if enabled in the IRQ \ i 

Mask Register at 53274 ($D01A). When this occurs, you can incorporate an interrupt jj 

routine to be activated upon the collision of two sprites. Therefore, your sprite-to-data 
collision interrupt routine is only executed upon the condition that a sprite has collided 
with an object on the screen foreground. Again, this gives you a way to conditionally \ i 

wedge an IRQ routine into your application program depending on the behavior of your '-' 

animated graphic objects on the screen. 

Note that sprite-to-data collisions do not occur with multi-color bit pair 01 } j 

(binary). This permits those bits to be interpreted as background display data, without U 

interfering with sprite-to-data collisions. 
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THE 8563 VIDEO CHIP 
FEATURES 



PROGRAMMING THE 
80-COLUMN (8563) CHIP 

Programming the 8563 video chip is a quite different from programming the VIC chip. 
As you know, the registers of the VIC chip are located in the range 53248 ($D000) 
through 53296 ($D030) in bank 15. Unlike the VIC chip, the 8563 has only two 
memory locations in Commodore 128 I/O memory. $D600 and $D601. This means that 
only two memory locations in the Commodore 128 I/O memory pertain to the 8563 
video chip. Internally, the 8563 has thirty-seven internal registers, though they are not 
addressable in C128 I/O memory. In addition, the 8563 has 16K of RAM of its own that 






The Conmiodore 128 computer offers two types of video output: 40-column, composite 

video through the VIC chip and 80-column, RGB! through the 8563 chip. The 80-column 

display adds an important feature to the Commodore family of home and business j j 

computers: The C128 can be regarded as a business machine. The 8563 chip enables the >— - 

C128 to display spreadsheets, wordprocessors, database managers and existing CP/M 

applications in 80 columns. Now, the latest in the family of inexpensive Commodore | j 

computers runs the Perfect series of business applications, and many other business JJ 

applications in C128 mode. In CP/M mode, the C128 runs Wordstar, and many other 

popular business applications. In addition, the CI 28 supports all the hardware and ^ , 

software available for the Commodore 64. The Commodore 128 is truly the complete \ \ 

personal computer. ^ 



U 



U 



! i 



The primary purpose of the 8563 video chip is to display characters on the screen. The 

8563 has two sets of characters, each with 256 elements. Unlike the VIC chip, however, 

the 8563 can display all 512 characters simultaneously. The VIC chip displays only one i-' 

character set at a time. 

The 8563 chip supports a limited bit map mode. Bit mapping can be achieved \ | 

through your own programs, preferably machine language. The BASIC 7.0 graphics Jj 

commands do not support the 80-column screen. Programming the bit-mapped screen in 
BASIC is not recommended, since the language is not geared to manipulating single 
display bits at a time. Later in this chapter, bit mapping the 80-column screen is 1 j 

illustrated in machine language. 

Another feature of the 8563 is smooth scrolling in the vertical and horizontal 
directions. The 8563 chip is equipped with a set of scrolling registers that enable text to 
be scrolled up, down, left or right. This is discussed later in the chapter. 
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is independent of the Commodore 128 RAM. You must address locations $D600 and 
$D601 as the gateways through which you indirectly address the thirty-seven internal 
registers and 16K of 8563 RAM. You cannot directly access any of the thirty-seven 
internal registers or the 16K of 8563 RAM. 

Location $D600 is the Address Register, and $D601 is the Data Register. 
Generally, you place an 8563 register number in the address register ($D600) then either 
write to or read from the data register in location $D601 . This is a simplified explanation — 
the more-detailed information given in the following sections is needed to program the 
8563 successfully. 



n 
n 

n 



8563 NOTES: 

1. You cannot use BASIC PEEK, POKE, or WAIT instructions to access 
the 8563, because these commands are implemented using indirect 
operations. Any indirect machine instructions (such as LDA ( ),Y or 
STA( ),Y) must be avoided because they result in 'false' bus states 
which are sensed by the 8563 and subsequently acted upon as though 
they were valid instructions. 

2. You should not, directly or indirectly, access the 8563 during inter- 
rupts, because there is no way to save and restore the 8563 registers 
without disrupting any I/O that might have been in progress at the 
time of the interrupt. 



DETAILS BEHIND PROGRAMMING 
THE 80-COLUMN CHIP 

So far, you have learned that the 8563 chip has: 

1. Thirty-seven internal registers. 

2. 16K of independent RAM (that is not addressable in the C128 memory map). 

3. An address register ($D600 and a data register $D601) in C128 I/O memory. 



Figure 10-1 is a summary of the 8563 registers, in the form of a register map: 
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BITS 






REG 


7 


6 


5 


4 


3 


2 


1 







HT7 


HT6 


HT5 


HT4 


HT3 


HT2 


HTl HTO 


Horizontal Total 


1 


HD7 


HD6 


HD5 


HIM 


HD3 


HD2 


HDl HDD 


Horizontal Displayed 


2 


HP7 


HP6 


HP5 


HP4 


HP3 


HP2 


HPl HPO 


Horizontal Sync Position 


3 


VW3 


VW2 


VWl 


VWO 


HW3 


HW2 


HWl HWO 


Vert/Horiz Sync Width 


4 


VT7 


VT6 


VTS 


VT4 


VT3 


VT2 


VTl VTO 


Vertical Total 


5 


— 


— 


— 


VA4 


VA3 


VA2 


VAl VAO 


Vertical Total At^ust 


6 


VD7 


VD6 


VD5 


VIM 


VD3 


VD2 


VDl VDO 


Vertical Displayed 


7 


VP7 


VP6 


VP5 


VP4 


VP3 


VP2 


VPl VPO 


Vertical Sync Position 


8 


— 


— 


— 


— 


— 


— 


IMl IMO 


Interiace Mode 


9 


— 


— 


— 


CTV4 


CTV3 


CTV2 


CTVl CTVO 


Character Total Vertical 


10 


— 


CMl 


CMO 


CS4 


CS3 


CS2 


CSl CSO 


Cursor Mode, Start Scan 


11 


— 


— 


— 


CE4 


CE3 


CE2 


CEl CEO 


Cursor End Scan Line 


12 


DSIS 


DS14 


DS13 


DS12 


DSll 


DSIO 


DS9 DS8 


Display Start Address hi 


13 


DS7 


DS6 


DS5 


DS4 


DS3 


DS2 


DSl DSO 


Display Start Address lo 


14 


CP15 


CP14 


CP13 


CP12 


CPU 


CPIO 


CP9 CP8 


Cursor Position hi 


15 


CP7 


CP6 


CPS 


CP4 


CP3 


CP2 


CPl CPO 


Cursor Position lo 


16 


LPV7 


LPV6 


LPV5 


LPV4 


LPV3 


LPV2 


LPVl LPVO 


Light Pen Vertical 


17 


LPH7 


LPH6 


LPH5 


LPH4 


LPII3 


LPH2 


LPHl LPHO 


Light Pen Horizontal 


18 


UA15 


UA14 


UA13 


UA12 


UAll 


UAIO 


UA9 UA8 


Update Address hi 


19 


UA7 


UA6 


UA5 


UA4 


UA3 


UA2 


UAl UAO 


Update Address lo 


20 


AA15 


AA14 


AA13 


AA12 


AAll 


AAIO 


AA9 AA8 


Attribute Start Adr hi 


21 


AA7 


AA6 


AAS 


AA4 


AA3 


AA2 


AAl AAO 


Attribute Start Adr lo 


22 


CTH3 


CTH2 


CTHl 


CTHO 


CDH3 


CDH2 


CDHICDHO 


Character Tot(h), Dsp(V) 


23 


— 


— 


— 


CDV4 


CDV3 


CDV2 


CDVICDVO 


Character Dsp(v) 


24 


COPY 


RVS 


CBRATE 


VSS4 


V,S,S3 


VSS2 


VSSl vsso 


Vertical smooth scroll 


25 


TEXT 


ATR 


SEMI 


DBL 


HS.S3 


HSS2 


HSSl HSSO 


Horizontal smooth scroll 


26 


FG3 


FG2 


FGl 


FGO 


BG3 


BG2 


BGl BGO 


Foregnd/Bgnd Color 


27 


A17 


AI6 


AI5 


AI4 


AI3 


AI2 


All AIO 


Address Increment / Row 


28 


CB15 


CB14 


CB13 


RAM 


— 


— 


— — 


Character Base Address 


29 


— 


— 


— 


UL4 


UL3 


UL2 


ULl ULO 


Underline scan line 


30 


WC7 


WC6 


WC5 


WC4 


WC3 


WC2 


WCl WCO 


Word Count 


31 


DA7 


DA6 


DAS 


DA4 


DA3 


DA2 


DAI DAO 


Data 


32 


BA15 


BA14 


BA13 


BA12 


BAll 


BAIO 


BA9 BA8 


Block Start Address hi 


33 


BA7 


BA6 


BA5 


BA4 


BA3 


BA2 


BAl BAO 


Block Start Address lo 


34 


DEB7 


DEB6 


DEBS 


DEB4 


DEB3 


DEB2 


DEBl DEBO 


Display Enable Begin 


35 


DEE7 


DEE6 


DEES 


DEE4 


DEE3 


DEE2 


DEEl DEEO 


Display Enable End 


36 


— 


— 


— 


— 


DRR3 


DRR2 


DRRIDRRO 


DRAM Refresh rate 


37 




HSyNCVSyNC 


— 


— 


— 


— — 


Horiz, Vert Sync Polarity 



Figure lO-l. 8563 VDC Register Map 

The numbers in the left column are the register numbers. When programming the 
8563, the registers are referenced by number only, since they have no actual address in 
the C128 memory map. Within the register map, columns 7 through apply to the bits 
within the registers. To the right are the register names, by function. Many of the 
registers control more than one operation of the chip, so the names only reference the 
primary purpose of the register. These registers are discussed individually at the end of 
this chapter. Certain key registers are discussed in the next section. For an explanation 
of each register, see the register-by-register description in the back of this chapter. 
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The 16K of 8563 RAM is organized by the Kemal in the following default 
structure: 



TYPE OF MEMORY 8S63 RAM LOCATION 

Character Display area (screen) $0000-$07FF 

Character Attributes (color) $0800-$0FFF 

Character Definitions $2000-$3FFF 



The layout can be changed by your application program. Registers 12 and 13 (high 
byte/low byte) specify the start of the character display area, which is comparable to 
screen RAM in the VIC chip. Registers 20 and 21 (high byte/low byte) specify the 
character attribute base address. These registers determine the starting address of display 
characteristics of a character such as reverse video, underlining, flashing and color. 
Register 28 determines the character set base address, the start of the character defini- 
tions in 8563 RAM. 

As you can see, the 8563 display has the same three components as the 
VIC display: screen memory, color memory, and character definitions. All three lie 
in the 16K of 8563 RAM and do not show up in the CI 28 memory map. These 
components of the 8563 video display are discussed in greater detail in the next 
section. 

The third element of 8563 programming is the address and data registers that 
are located in locations $D600 and $D60I. These locations are the transitions, the 
doorways in and out of the 8563 chip. You cannot directly reference an 8563 
register or RAM location. You must indirectly read or write to $D600 and $D601 in 
order to communicate between the 8563 chip and the rest of the Commodore 128. 
Figure 10-2 gives description of each of the mapped registers and the bits within 
them: 



$D600-» address (write): 
status (read) : 


— — R5 R4 R3 R2 Rl RO 
STATUS LP VBLANK — — VERO VERl VER2 


$D601^ data (r/w) : 


D7 D6 D5 D4 D3 D3 D2 DO 



Figure [0-2. Mapped Registers 



In location $D600, bit 7 acts as a status bit. When you require a read or write 
operation to the 8563 RAM or a register, you must check the value of bit 7 of 
$D600. While it is 0, no read or write operations may take place. 
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This is the sequence of steps to perform a read or write operation: 

1. Address the registers (by number) or internal RAM location. j I 

2. Check the value of bit 7 until it equals 1 in order for the data to be lJ 
valid. 

3. Once bit 7 becomes high (1), perform the read or write operation. 



Later in this chapter, you'll see example programs that illustrate the behavior of 
these registers. 

The rest of the bits in $D600 except bit 6, which involves a light pen are used to 
represent a register number for read or write access. Six bits are necessary since the 
8563 has 37 registers; therefore, enough bits are needed to represent numbers up to 37. 

Location $D601 is strictly a data register that passes values between tiie 8563 I I 

and the 8502 during read and write operations respectively. Each bit in this register [J 

is a data bit. All data that passes between 8563 and the 8502 must pass through this 
register. 



u 



FUNDAMENTAL BACKGROUND 
ABOUT THE 8563 CHIP 



CHARACTERS 

As you know, the 8563 < 

by 25 character matrix. 

can be defined by 16 or 32 bytes and can be displayed less than 8 by 8 pixels. 



As you know, the 8563 chip is primarily designed for displaying characters within an 80 
by 25 character matrix. The visible character is an 8 by 8 pixel matrix. The character 
can be defined bv 16 or 32 bvtes and can be disnlaved less than 8 hv 8 nixe.ls U 

LJ 
U 
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a. Visible 8 by 8 pixel character. 

b. Horizontal intercharacter spacing. 

c. Vertical intercharacter spacing. 

Figure 10-3. 



The horizontal unit of measure within a character is a pixel. The vertical unit of 
measure within a character is called a scan line. A scan line is a single horizontal row of 
scanned pixels referred to as one raster. The pixel and the scan line are the smallest units 
of measurement by the 8563 chip in the horizontal and the vertical directions, respec- 
tively. The size of the displayed character image in both pixels and scan lines is 
programmable and determined by four registers within the 8563: the Character Total 
(R9) (vertical), Character Total (R22) (horizontal), Character Displayed (R23) (vertical) 
and Character Displayed (R22) (horizontal) Registers. These registers are described in 
the register by register description at the end of this chapter. 

FRAMES 

A frame is a two-dimensional array (matrix) of characters, also referred to as simply the 
screen. The default frame is the 80-column by 25-line screen in which characters are 
displayed. Each character on the frame has a character pointer (a Display RAM byte) 
that tells the 8563 which character to display in each character position within the frame. 
Think of a frame as a framed picture on a wall containing a two-dimensional array 
(matrix) of characters. For example, a frame specified to be 16 by 12 characters is filled 
with characters as in Figure 10-4. 

The frame also contains the vertical retrace and all other nonvisible portions of the 
screen. The frame is programmable in size, similar to a window. The screen frame 
determines the size of the viewed image, like the frame surrounding a window. 
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HASADKHADKSFDKHA 
HASADKHADKSFDKHA 
HASADKHADKSFDKHA 
HASADKHADKSFDKHA 
HASADKHADKSFDKHA 
HASADKHADKSFDKHA 
HASADKHADKSFDKHA 
HASADKHADKSFDKHA 
HASADKHADKSFDKHA 
HASADKHADKSFDKHA 
HASADKHADKSFDKHA 
HASADKHADKSFDKHA 



Figure 10-4. 



The default frame size is 80 columns by 25 lines. However, the frame size and 
characteristics are programmable, so you can change them. The 8563 has several 
registers that determine the size and characteristics of the frame. These registers are as 
follows: 

Horizontal Total (RO) 
Horizontal Displayed (Rl) 
Horizontal Sync Position (R2) 
Horizontal Sync Width (R3) 
Vertical Total (R4) 
Vertical Total Adjust (R5) 
Vertical Displayed (R6) 
Vertical Sync Position (R7) 
Vertical Sync Width (R3) 
DRAM Refresh/Scan Line (R36) 

These registers are covered in the register-by-register description at the end of the 
chapter. 
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UNDERSTANDING THE 80-COLUMN 
CHARACTER DISPLAY AND 
ATTRIBUTE MEMORY 



As you learned earlier in this chapter, the 8563 has three areas of memory that control 
the 80-column display: character definitions, character attributes and display screen 

|— I memory. 

I j In a previous section, the three main elements of programming the 80-column chip 

were introduced: (1) the address and data registers $D600 and $D601 that map into the 
C128 RAM memory map, (2) the 16K of independent 8563 RAM, and (3) the 37 
internal registers. The 16K of independent 8563 RAM provide the main elements of 
video display information: display memory, character attributes and character definitions. 
The display memory is comparable to screen memory in the VIC chip. The character 
attributes supply color and other information for the characters and parallel the function 
of VIC color RAM. The 8563 character definitions correspond to the VIC character 
ROM. Though the VIC and 8563 video memory are similar, the operations of the two 
are different. This provides a frame of reference to the VIC chip characteristics, so you 
can understand the comparison between the operation of both the VIC and 8563 video 
processors. 

All these video components are stored in the 16K of independent 8563 RAM. 
Again, here is the breakdown of the locations where the three sections of video memory 
are stored in the 8563 RAM: 



TYPE OF MEMORY 8563 RAM LOCATION 

Display Memory $0O0a-$O7FF 

Character Attributes $0800-$OFFF 

Character Definitions $2000-$3FFF 



All of the 8563 video display memory resides in the 16K section of independent 
RAM. The 8563 character definitions in RAM require up to 32 bytes per character. If 32 
bytes per character are used, the 8563 character definitions use 8K of memory per 
character set, or a total of 16K. Otherwise, each character set occupies 4K of indepen- 
dent 8563 RAM, or a total of 8K for both character sets. The VIC chip requires a total 
of 4K of character ROM to represent all the characters, since the VIC chip only requires 
8 bytes to represent a character. 

The rest of the section describes how the character display area, the character 
attributes and the character definitions are addressed and interpreted. 
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UNDERSTANDING 
DISPLAY MEMORY 



$0000-$07FF in the 16K independent 8563 RAM. Think of the screen as a frame of 25 
rows of 80 characters each. A frame may have different proportions, but for the 
purposes of this discussion, assume that the frame is 80 by 25. 

Each character position (display memory location) within a frame contains a 
code that acts as a pointer into the character defmitions that tells the 8563 which 
character to display in that particular character position within the frame. For the 
defined screen of frame size 25 rows by 80 columns, the first 80 pointers define the 
character codes for the 80-character positions in the top row of the screen (frame). 
Locations 81 through 160 define which characters are displayed in the second row of 
the screen (frame), and so on. For the defined screen frame of 80 by 25, 2000 
display memory locations are necessary to display the 2000 possible character positions 
of the screen. 

In text mode, the contents of display RAM are screen display codes like the 
ones the VIC chip uses. These are not ASCII CHR$ codes. Screen codes are actually 
indexes into the 8563 character RAM definitions, like the screen codes used as indexes 
into the VIC character ROM. Since the first character in 8563 character RAM is 
the at-sign character, it is assigned screen code 0. The A is the second character, 
so it is assigned the screen code 1, and so on. For a complete list of screen codes, 
see Appendix D. 



ADDRESSING 
DISPLAY MEMORY 



The contents of registers 12 (high-byte) and 13 (low-byte) define the 16-bit start address 
of the first (top-left) character in the frame (display memory). The default start address 
of display memory is $0000. The address of the second character position on the 
frame, that is, the character in column two, row one, is defined by the contents of 
registers 12 and 13 plus 1. Add an index to the contents of registers 12 and 13 to arrive 
at the address of subsequent character positions on the frame. For example, to find the 
address of the character position in the first column of the second row of an 80 by 25 
frame, add an offset of 80 to the contents of registers 12 and 13. To find the address of 
the character position in column 1, row 3, add 160 to the contents of registers 12 
and 13. 



u 



The frame, which was introduced earlier in this chapter, pertains to display memory, the 
portion of memory you can see on the screen. Display memory resides in the range 
.<l;00n0-.t;n7FF in the. 16K indenenHent 8563 RAM Think of the. srrep.n as a framp. of ^S J 
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In general, add an offset of 1 for each character position to the right of the 
^ upper-left comer of the frame. To reach the same column in the row below the current 

) I character position, add an offset of 80. Although the screen (frame) appears as a 

two-dimensional matrix of characters, the address references in memory are accessed 

linearly in sequence. For example, although the character in the top-left comer of the 
n screen is only 24 character rows away from the character in the lower-left comer of the 

' ' screen, in memory, the locations of those characters are really 1920 (24 x 80) memory 

locations apart. So a frame, the size of the default screen (80 x 25) requires 2000 
n memory locations to store the contents of the 2000 character positions on the 

I ! frame. The contents of each display RAM location (acting as an indexed pointer into the 

character definitions) tells the 8563 which character, out of the 256 available characters 
pj in either character set, to place at any particular position on the 80 by 25 character 

1 frame. 



n 



CHARACTER ATTRIBUTES 



The character attributes are a set of 8563 RAM locations that assign video enhance- 

ment qualities to the characters in the frame. Each character position in the frame 
n is assigned its own attribute byte, so a frame (screen) of 80 columns by 25 lines 

' ' requires 2000 attribute bytes. The default location of the attribute bytes for the 80 

by 25 frame is stored in the range $0800 through $OFCF in the 16K of independent 
n 8563 RAM. 

I I The attributes (and the corresponding bits) that enhance the video qualities of the 

characters in the frame are as follows: 

n 



BIT 


ATTRIBUTE 


7 


Alternate Character Set 


6 


Reverse Video Attribute 


5 


Underline Attribute 


4 


Blink Attribute 


3 


Red 


2 


Green 


1 


Blue 





Intensity 



The ALTERNATE CHARACTER SET (bit 7), when high (1), enables an 
additional 256 characters to be displayed within the frame. 
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1 


Black 


9 


Dark Purple 


2 


White 


10 


Dark Yellow 


3 


Dark Red 


11 


Light Red 


4 


Light Cyan 


12 


Dark Cyan 


5 


Light Purple 


13 


Medium Gray 


6 


Dark Green 


14 


Light Green 


7 


Dark Blue 


15 


Light Blue 


8 


Light Yellow 


16 


Light Gray 



ADDRESSING CHARACTER ATTRIBUTES 

The contents of registers 20 (high-byte) and 21 (low-byte) define the address of the start 
of attribute storage. The default start address of attribute storage is $0800. The 
contents of these two registers form the 16-bit address that marks the start of attribute 
storage. 

Address these attributes in the same way as addressing display memory. 
To address subsequent character attributes to the right of the character in the HOME 
(upper-left) position of the frame, add an offset of 1 to the contents of registers 



u 





The REVERSE VIDEO ATTRIBUTE (bit 6), when high (1), reverses the 
foreground and background colors for the corresponding character in display memory. 
See also the register-by-register description of the 8563 chip for all the details about 
register 24, the Reverse Screen Register. 

The UNDERLINE ATTRIBUTE (bit 5), when high'(l), enables the UNDER- 
LINE SCAN LINE (as defined by bits through 4 of register 29) in the foreground I i 
color for that character within the frame. The underline scan line may be any scan line Lj 
within the character as determined by the lower four bits of register 29. 

When the BLINK ATTRIBUTE (bit 4) is equal to 1, the character associated 
with this attribute byte blinks. The blinking is achieved by repeatedly switching back [_ 

and forth between the foreground and background colors. The blink rate is determined 
by bit 5 of register 24. r , 

Attribute bits 3 through determine the foreground color for the R, G, B and I j | 

respectively. The character within the associated display memory appears in the fore- '"^ 

ground color determined by the R, G, B and I bits. The foreground color of each 
character cell can be one of 16 colors. The actual colors on the screen can be more than 
red, green and blue. The RGBI signals coming from each input and the combination of 
these signals determine the actual screen color. Here are the available colors and 
associated color codes. The characters' background color is determined by bits 
through 3 of register 26. These bits in register 26 specify the background color for all 
the characters on the screen. Note, however, that in machine language these codes are 
one less than the BASIC codes. 
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BASIC Color Codes in 80-Column Output i 
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20 and 21 for each character attribute to the right of the HOME position. To address the 
character attribute directly below the HOME position (row 2, column 1), add an offset 
of 80 to the contents of registers 20 and 21. To address the character attribute of the 
character in the lower-left comer of the 80 by 25 frame, add a decimal offset of 1920 
(24 X 80). 

DISABLING CHARACTER ATTRIBUTES 

Many applications programs for the 8563 chip do not need to assign the character 

attributes. The 8563 has a bit that allows attributes to be disabled, saving a considerable 

amount of RAM. Bit 6 of register 25 determines whether or not attributes are enabled. If 

bit 6 is set (1), attributes are enabled: if the value of bit 6 is 0, attributes are disabled. 

n When attributes are disabled, the attribute portion of 8563 RAM may be used for other 

/ I purposes. If attributes are disabled, only one set of 256 characters is available, and 

underlined, blinking and reverse video attributes are not available. In addition, all 

pi characters are displayed in the same foreground color as determined by bit 4 through 7 

I I of register 26. The background color is still determined by the lower four bits (3-0) of 

register 26, regardless of whether attributes are enabled or not. The screen border and 

the vertical and horizontal intercharacter spaces default to the background color. 

Display memory may contain more memory locations and attributes than can be 
displayed at a single time in an 80 by 25 frame. This portion of display memory may be 
displayed by changing the contents of registers 12 and 13, the Display Start address, and 
registers 20 and 21, the Attribute Start address, to reflect a new start of display memory 
and attribute storage. The screen (frame) may be scrolled vertically by incrementing or 
decrementing the values of the display memory pointer and attribute start addresses. 
This provides a way to vertically scroll forward or backward through display memory. 
In addition to scrolling vertically through display memory, the 8563 has a feature 
that allows scrolling through display memory in the horizontal direction. Both of these 
topics are covered later in this chapter. 



CHARACTER DEFINITIONS 



The character definitions residing in 8563 RAM specify the character patterns you see 
on the 80-column screen. The character patterns in memory define the pixel formation 
of each member of the character set visually represented on the screen. The character 
definitions can be redefined by your application program. 

The default memory range for the character definitions is locations $2000 through 
$3FFF in 8563 RAM. This range is a total of 8K (8192 bytes). This is enough memory 
to represent two character sets of 256 characters each. The attribute bit 7 of each 
attribute byte selects either of the character sets for each character position within a 
frame. 

The 8563 characters are represented by either 16 or 32 bytes, depending on the 
value of the lower five bits (4-0) of register 9. If the value of the lower five bits of 
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ADDRESSING THE 
CHARACTER SET PATTERNS 



READING 8563 

(RAM AND) REGISTERS 

As you know, the 8563 chip has its own 16K of RAM and its own set of registers. 
Neither of these appear in the standard Commodore 128 memory map. The only 
memory locations that apply to the 8563 chip in Commodore 128 memory are the locations 



u 



register 9 is less than 16, each character is defmed by 16 bytes in character storage. 
Therefore, each character set requires a total of 4096 bytes of 8563 RAM. If the value 
of the lower five bits of register 9 is greater than or equal to 16, each character is j 

defmed by 32 bytes of 8563 character RAM. In this case, each character set occupies U 

8192 bytes (8K) of 8563 character RAM memory and the defmed characters are 
displayed using more than 16 scan lines each. This occupies the full 16K of 8563 RAM ( 

and leaves no space for attributes. These taller characters are rarely used, however, ' 

because the characters are twice as tall as they are wide and seem out of proportion. 

The first byte of each character definition in memory represents the top horizontal 
scan line of the character displayed on the screen. Depending on the value of the lower 
five bits of register 9, a character will have either 16 or 32 scan lines, each being 8 bits '-' 

(pixels) wide. 

Although the character definitions in 8563 character RAM are defined by either 16 
or 32 8-bit bytes stacked one on top of another, the Display Data Bus is only 8 bits 
wide, which limits the actual image of the character to 8 horizontal pixels. The total 
width of the character including the horizontal intercharacter spacing may exceed 8 : , 

pixels. See the definition of a character in the beginning of the chapter and the 
register-by-register description at the end of this chapter for details. 







u 
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The default location of the character definition start at address $2000 in 8563 RAM, and 

since the starting location is programmable, you may change it. The starting location of j | 

the character set definitions is determined by bits 5 through 7 of register 28. These are ^ 

the most significant three bits of the 16-bit address that points to the start of the 

character definitions in 8563 RAM. Bits 4 through of register 9 make up the five least 

significant bits for the address that points to the start of the 8563 character definitions. 

However, if the value of bits 4 through in register 9 is greater than or equal to 16, only 

bits 7 through 5 are significant, since the characters are made up of 32 bytes each and ; 

the full 16K of 8563 RAM memory is allocated for the two character sets, 8K for each 

set. 
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D600 and $D601. These are the 8563 address and data registers, respectively. In order 
to read or write to 8563 RAM or registers, you must pass data through the address and 
data registers. This section explains how to read the 8563 registers. The next section 
illustrates how to write to the 8563 registers and RAM. 

READING AN 8563 REGISTER 

Reading an 8563 register requires five distinct programming steps. Although this may be 
accomplished in BASIC, it is strongly recommended that you program the 8563 in 
machine language. Briefly, here are the five machine language programming steps, the 
algorithm, to read an 8563 register. A more detailed explanation and a program to read 
an 8563 register follows. 

1. Load (immediate) the X register with the register number that you want to 
read. 

2. Store the contents of the X register (the 8563 register number) into the 8563 
address register ($D600). 

3. Check the status bit, bit 7 of address register $D600, until it is high (1). 

4. If the status bit is low (0), go back and check it again. 

5. Otherwise, load the accumulator with the contents of the 8563 data register 
$D601. Store the contents of the data register into a C128 RAM location (a 
variable) for future use and print the variable yalue. 

Since many of the 8563 registers are pointers to a 16-bit address, a register pair is 
required, one register for the high byte and one for the low byte. In this case, simply 
increment the X register and repeat the five-step process to read the register contents of 
the low byte. The high-byte register comes first in the register order, therefore the first 
read is the high byte of a register pair, increment the X register and repeat the 
process for the low byte. When the 8502 uses a register pair to point to a 16-bit 
address, the high byte is the low byte plus 1. 

Here's a program that reads the high- (R20) and low- (R21) byte register pair that 
acts as a pointer to the start of the attribute storage in the 8563 RAM. The value stored 
in locations $FB and $FC return the default start (high/low byte) of the attribute storage. 
This pointer can be relocated to point to a section of 8563 RAM in which you define, as 
is the case for display RAM and the character patterns. 

EXAMPLE: 

Reading a register (attribute base address) 
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10 SYS DEC("1800") 

20 AS=HEX$(PEEK(251)) 

30 BS=HEX$(PEEK(252)) 

40 CS=RIGHT$(A$,2) 

50 DS=RIGHT${BS,2) 

60 ES=C$+DS 

70 FS="S" 

80 G$=F$+E$ 

90 PRINT "START ADDRESS = ";GS 

READY. 

MONITOR 

PC SR AC XR YR SP 
; FBOOO 00 00 00 00 F8 

. 01800 A2 14 LDX #$14 

. 01802 20 OF 18 JSR S180F 

. 01805 85 FB STA $FB 

. 01807 E8 INX 

. 01808 20 OF 18 JSR ?180F 

. 0180B 85 FC STA $FC 

. 0180D 60 RTS 

. C180E 00 BRK 

. 0180F 8E 00 D6 STX SD600 

. 01812 2C 00 D6 BIT $D600 

. 01815 10 FB BPL $1812 

. 01817 AD 01 D6 LDA $D601 

. 0181A 60 RTS 



Here are the details behind each instruction. 



u 
u 

u 
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The first instruction ($1800) loads the X register with register number 20 ($14), 

the high byte of the attribute start address. 

The second instruction jumps to the subroutine at $180F. 

The first instruction of the subroutine stores the contents of the X register, 

($14), into the 8563 address register (location $D600 in C128 I/O memory). 

The second instruction of the subroutine (BIT $D600) tests the UPDATE 

READY status bit (7) of the 8563 address register. This is necessary since a 

read or write operation does not take place as soon as those instructions are issued. 

The Update Ready bit (bit 7) of the 8563 Address register determines when the 

read (or write) instruction can be executed. The read operation is pending according 

to the value of bit 7 of the address register. While the read operation is pending r 

(in prelatch), the value of bit 7 is 0. This indicates that tiie read (or write) j 

operation data placed in register 3 1 , is not yet valid. Only when the value of bit 

7 in the address register is equal to 1 , is the data in the data register ($D601) valid. 



u 
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The behavior of the 8563 chip and the way data is transferred between the 8563 
registers and the address and data registers suggests the use of the BIT instruction. The 
nature of the 8502 BIT instruction is tailor-made for checking the Update Ready bit 
status of location $D600. When the BIT instruction is encountered by the microproces- \ I 

sor, the value of bit 7 is transferred into the negative flag bit of the 8502 status register. U 

If the value is equal to 0, the negative condition does not exist. If the value is equal to 1 , 
a negative condition does exist. Depending upon the value of this bit, you can condition- 
ally branch to instructions that carry out an operation according to the value of this flag. 
That's where the third instruction in the above subroutine ($1815) comes into play. 
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■ Instruction 3 (BPL $1812) is a conditional instraction that branches depending 
upon the value of the negative flag bit in the 8502 status register. In this 
program, the BPL (Branch on Result Plus) instruction branches back to 
location $1812 and executes the BIT instruction while the negative flag bit is 
equal to 0. The BIT instruction is again performed, and the value in bit 7 is 
again transferred to the negative flag bit in the 8502 status register. Then the 
BPL instruction is encountered in the loop for a second time. If the value of the 
status bit is still equal to 0, the branch is performed again. The loop continues 
until the negative status bit is equal to one. Only when the status bit is equal to 
1 does the loop fall through to the instruction immediately following the branch 
instruction. 

Prior to the loop falling through to the instruction after the branch, the 
Update Ready status bit becomes a 1 , it is transferred to the negative flag bit in 
the 8502 status register, the branch is skipped, and the data can be read (loaded 
with the fourth instruction of the subroutine ($1817) into $D601. Only after the 
status bit becomes high (1) is the data in $D601 valid. This is the point where the 
data is communicated from the 8563 chip to the Commodore 128 memory. Now 
you can read and act upon the contents of the address within register $14 of the 
8563 chip. 

■ The fourth instruction loads the value stored in the 8563 data register ($D601) 
into the accumulator. 

■ The third instruction of the main program stores the value of the data register 
—, into location $FB for future use. Subsequent read operations from ($D601) 
j I destroy the original value, so it is always a good practice to store the contents of 

$D601 into a variable or available RAM location. 

■ The next instruction, INX, increments the contents of the X register, which 
I j selects the next register number, $15, so the low byte of the 16-bit address 
'' ^ of the start of attribute storage can be read. 

■ The rest of the program performs the same sequence of steps above for the 
p* low byte of the start of attribute storage except for the RTS instruction. The 
i i RTS instruction returns program control back to a main program. 

1^ The BASIC portion of the program prints the high and low bytes of the 16-bit 

j I address that defines the start of attribute storage. 

To find the actual address in 8563 RAM of the start of attribute storage, put the 
high byte and low byte together, and the four-digit hexadecimal number defines the start 
r? of attribute storage. Within the monitor, issue this memory command: 

' ' MFB 

/— t The contents of $FB and $FC (high/low bytes) mark the start of attribute storage. 



n 
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The five-step algorithm to read data from an 8563 register is similar to writing to an 
8563 register. In the last section, Step 5 in the read algorithm loaded the accumulator ] j 

with the value contained in the 8563 data register ($D601). When writing, perform the !j 

opposite operation. Instead of loading the accumulator as in a read operation, store the 
accumulator value into the data register. , i 

Here's an algorithm to write to an 8563 register: 







1. Load the X register with the register number in which you want to write. 

2. Load the accumulator with a value that you are writing to the 8563 register. 

3. Store the contents of the X register into the 8563 address register at $D600. 

4. Check bit 7, the status bit, of the Address Register until it is high (1). 

5. If the status is low (0), loop back and check it again until it is high. ^ . 

6. When the status bit (7) is high, store the value contained in the accumulator I 
into the 8563 data register ($D601). '-' 

Here's a sample program that writes to register pair R18 and R19, the Update RAM j I 

location. Register pair R18 and R19 is the gateway into the independent 8563 RAM. For [_j 

now we'll illustrate how to write to an 8563 register. Later in this chapter, we'll take 
it a step farther to explain how to read and write to the 16K of independent 8563 RAM. 

READY. 



LJ 



MONITOR 












PC 


SR AC XR 


ra SP 


; FBOOO 


00 00 00 


00 F8 


. 01800 


A2 


12 




LDX 


#S12 


. 01802 


A9 


20 




LDA 


#?20 


. 01804 


20 


IE 


18 


JSR 


$181E 


. 01807 


E8 






INX 




. 01808 


A9 


00 




LDA 


#$00 


. 0180A 


20 


IE 


18 


JSR 


$181E 


. 0180D 


EA 






NOP 




. 0180E 


A2 


12 




LDX 


#$12 


. 01810 


20 


20 


18 


JSR 


$1820 


. 01813 


85 


FB 




STA 


$FB 


. 01815 


E8 






INX 




. 01816 


20 


20 


18 


JSR 


51820 


. 01819 


85 


FO 




STA 


$FC 


. 0181B 


60 






RTS 




. 0181C 


GO 






BRK 




. 0181D 


00 






BRK 




. 0181E 


8E 


00 


D6 


STX 


$D600 


. 01821 


20 


00 


D6 


BIT 


$D600 


. 01824 


10 


FB 




BPL 


$1821 


. 01826 


8D 


01 


D6 


STA 


$D601 


. 01829 


60 






RTS 




. 0182A 


EA 






NOP 




. 0182B 


EA 






NOP 




. 0182C 


8E 


00 


D6 


STX 


$D600 


. 0182F 


2C 


00 


D6 


BIT 


$D600 


. 01832 


10 


FB 




BPL 


$182F 


. 01834 


AD 


01 


D6 


LDA 


$D601 


. 01837 


60 






RTS 





u 



u 

u 
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■ The first instruction (at $1800) loads the X register with the register number 
18 ($12). 

|~j ■ The next instruction loads the accumulator with the high byte of the value you 

I i are placing in register 18 ($20). 

■ Instruction 3 calls the subroutine at location $181E, which is essentially the 
p* same routine as in the read register example in the last section, with one 
; ! exception. The instruction in the subroutine immediately before the RTS is a 

store instruction to the 8563 data register at $D601 . The two instructions before 
it form a loop that continually checks the Update Ready status bit pending the 
I I write operation, just as the read program did. The write operation (STA 

' I $D601) is not performed until the status bit 7 in the address register becomes 

high (1). Once the status bit becomes equal to a 1, the high byte of the address 
PI in register 18 is written to the data register ($D601). The subroutine returns 

; j control to the main body of the program with the RTS instruction. 

■ The program resumes with the fourth instruction INX. This increments the 
register number. 

■ The fifth instruction (LDA #00) loads the value of the low byte of the address 
to be written to register 19 ($13) into the accumulator. 

■ The subroutine at $18 IE is called again, and the same process is repeated. 

■^J ■ Upon return of the subroutine, the same read routine example from the last 

I section is performed (the subroutine between $182C-$1837) to ensure that the 

values that were written to registers 18 and 19 are valid. These values are 

,_^ printed by the BASIC routine. To see those values, use the memory command 

j I within the monitor as follows: 

MFB 

n The first two bytes displayed are: 

M 20 00 

_, This shows that the address in the update location register pair (R18, R19) has 

• j been written to successfully and is valid. 



ii 



WRITING TO 8563 RAM 



Now take the example from the last section one step farther. The last example illustrated 
how to write to an 8563 register. It just so happens that the register chosen for the 
example is the update location register pair (R18, R19). This is the register pair that 
enables you to write to and read from the 16K of independent 8563 RAM. This section 
expands on the previous example and shows you how to write to the 16K of 8563 RAM. 

The program given below fills display memory in 8563 RAM with characters, in 
the process displaying the characters on the screen. The program fills display RAM 
located in the default range $0000 through $07CF, with screen code character 102 
($66). See Appendix D for a complete list of screen code characters. 

Here's the listing: 
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READY. 












MONITOR 












PC 


SR AC XR 


iP. SE 




; FBOOO 


00 00 00 


30 F8 




. 01800 


A2 


12 




LDX 


#$12 


. 01802 


A9 


00 




LDA 


#500 


. 01804 


20 


21 


18 


JSR 


$1821 


. 01807 


E8 






I NX 




. 01808 


20 


21 


18 


JSR 


$1821 


. 0180B 


AO 


00 




LDY 


#$00 


. 0180D 


A9 


08 




LDA 


#$08 


. 0180F 


85 


FA 




STA 


$FA 


. 01811 


A9 


66 




LDA 


#$66 


. 01813 


20 


IF 


18 


JSR 


$181F 


. 01816 


C8 






INY 




. 01817 


DO 


FA 




BNE 


$1813 


. 01819 


C6 


FA 




DEC 


$FA 


. 0181B 


DO 


F6 




BNE 


$1813 


. 0181D 


00 






BRK 




. 0181E 


00 






BRK 




. 0181F 


A2 


IF 




LDX 


#$1F 


. 01821 


8E 


00 


D6 


STX 


$D600 


. 01824 


2C 


00 


D6 


BIT 


SD600 


. 01827 


10 


FB 




BPL 


$1824 


. 01829 


8D 


01 


D6 


STA 


$D601 


. 0182C 


60 






RTS 





G F1800 












u 

D 

To execute this program, issue the Go (G) command within the Machine Lan- jj 

guage Monitor. In order for this program to operate, I/O memory must be in context in 
the currently selected monitor configuration. I/O memory is always in context within 
configuration 15 ($F), so issue this command to execute die program: 



u 
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The first five instructions (memory $1800-$ 1808) and the subroutine stored in 
memory locations $1821 through $182C are the same instructions contained in the program 
that wrote to registers 18 and 19 in the last section. However, instead of placing the address 
$2000 in register pair 18 and 19 as in the last section, the address $0000 is placed 
there to mark the default starting location of display memory in 8563 RAM. This is where 
the program begins to place screen code 102 in display RAM. The full 2000 bytes (8 pages 
of memory minus 48 bytes) of display RAM are filled with this character screen code. 

Here's how the rest of the program works. The instruction stored at location 
$180B, LDY #$00, initializes the Y register to 0. The next instruction, LDA #$08 j J 

loads the accumulator with the value 8. Then, STA $FA, stores the contents of the 
accumulator, which initializes this location to 8. Location $FA is used later in the 
program as a counter for the number of pages to fill with screen code 102. The 
instruction stored at $1811, LDA #$66, loads the accumulator with the hexadecimal L 

value ($66) of decimal screen code 102. 

The instruction starting in location $1813, JSR $18 IF, calls the subroutine located ■ 

at address $181F. This subroutine is the crux of the program and actually writes the data ] | 

to the display memory (screen). This is essentially the same routine as the subroutine *— ' 

located between $181E and $1829, the one from the last section. However, there is one 
key difference. The first instruction of the subroutine stored starting at $181F, LDX \ 

#$1F, loads the X register with the register number 31 ($1F). When writing to 8563 ]__ 
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RAM, you must address register 31 because it acts as the internal data register of the 
8563 chip. All data that will be written to the 8563 RAM must pass through register 31. 
The next three instructions: 



STX $D600 
BIT $D600 
BPL $1824 

check the status bit (7) of the address register until the value becomes equal to 1 
(high). These are the same three instructions used in the last two sections when reading 
or writing to a register and in the first subroutine of this program. 

Once the status bit of the 8563 address register becomes high, the data residing in 
the accumulator (in this case) is written to the external 8563 data register at address 
$D601, as in the instruction stored at location $1829. In addition, the data in the 
accumulator is written to the address contained in the update register pair (R18, R19). 
This occurs since you addressed the internal data register 31 by placing the value 31 in 
the 8563 address register at $D600. Upon the status bit becoming high, all data in 
register 31 is placed in the current address of 8563 RAM specified by the update register 
pair (R18, R19). You placed this address in the update register pair in the very 
beginning of the program. 

At this point, the 8563 hardware takes over. It automatically increments the 
address contained in the update register pair (R18, R19). You as the programmer do not 
increment the update register pair's contents; the 8563 chip does this for you automati- 
cally. You can say that the update register pair is auto-incrementing. In addition, the 
8563 reads the data from the incremented address within 8563 RAM, and places the 
contents in the internal 8563 register 31. This also saves programming effort. Remem- 
ber, both of these tasks are performed by the 8563 hardware, not the programmer. 
I i Since the update register pair automatically increments the 8563 RAM addresses, 

' ^ all you have to do is continually call the subroutine that writes the data to each 

successive display RAM location. That's what the instructions between addresses $1813 
!"■ and $1813 do in the program. These instructions call the subroutine for eight pages of 

I J display RAM, or a total of 2048 times. The write subroutine writes only one character to 

the screen per call, so to fill the entire screen, it must be called 2000 (80 x 25) times. 
fm, This sample BASIC program shows how to properly read and write the 8563 

! 1 registers, and read, modify, write any location in 8563 RAM. The two ML subroutines 

are the key- and they can be used from either BASIC as shown here, or from your ML 
program. 
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100 VI=DEC( "1800" ) :VO=DEC( "180C" ) sBANKlB 
110 READ A$ 

115 DO UNTIL A$="END" 

116 : POKE VI+I,DEC(A$) 

117 : 1=1+1 

118 : READ A$ 

119 : LOOP 

120 : DATA 8E, 00,D6,2C,00,D6,10,FB,AD,01,D6,60 
130 : DATA 8E,00,D6,2C,00,D6,10,FB,8D,01,D6,60,END 
140 DO 

150 : PRINT 

160 : INPUT"ADDRESS (0-16383) ";AD 

170 : SYS VO, AD/256, 18 

180 : SYS VO, ADAND255,19 

190 ! SYS VI,, 31 

200 : RREG A 

210 ! PRINT"THE 8563 MEMORY AT";AD;" IS";A 

220 ! INPUT"NEW DATA (0-255) ";A 

230 ! SYS VO, AD/256, 18 

240 ! SYS VO, ADAND255,19 

250 : SYS VO, A ,31 

260 : LOOP 



(install ML routines) 



(update location HIGH) 
(update location LOW) 
(READ memory data) 

(update location HIGH) 
(update location LOW) 
(WRITE memory data) 



The following disassembly shows the two ML routines used in the previous BASIC 
program and in the Read register, Write register and Write to RAM examples in the 
preceding sections. They are relocatable. 



(routine to READ 8563 register in .X) 



01800 


8E 


00 


D6 


STX 


$D600 


01803 


2C 


00 


D6 


BIT 


$D600 


01806 


10 


FB 




BFL 


$1803 


01808 


AD 


01 


D6 


LDA 


$D601 


0180B 


60 






RTS 




0180C 


8E 


00 


D6 


STX 


SD600 


0180F 


2C 


00 


D6 


BIT 


$D600 


01812 


10 


FB 




BFL 


$180F 


01814 


8D 


01 


D6 


STA 


$D601 


01817 


60 






RTS 





(routine to WRITE .A register in .X) 
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BLOCK WmTE AND BLOCK COPY 

The 8563 chip's Block Write and Block Copy features are extensions of the write 
operation described in the last section. The Block Write feature writes the same data 
contained in the accumulator into a specified number of successive 8563 memory 
locations. Here's the procedure: 

1. Place the initial address, where writing in RAM begins, into registers 18 
(high byte) and 19 (low byte). 

2. Next, load the accumulator with the data you want to place in successive 8563 
RAM locations. 

3. Load the X register with the number 31 which specifies the data register 
within the 8563. 

4. Wait for the Update Status Ready bit to become high (1). So far this is the 
same procedure as writing to 8563 RAM which was described in the Writing 
to 8563 RAM section. 

5. To select the Block Write feature, clear (0) bit 7 of register 24, using the 
same procedure you use to write to a register. 
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6. Finally, place the number of successive memory locations you want to write 
to 8563 RAM in register 30. 

I \ At this point, the 8563 writes the data in register 31 starting from the location deter- 

mined by registers 18 and 19 through the number of successive memory locations specified 

I— I by register 30. The contents of registers 18 and 19 are automatically incremented to access 

j I the next location to be written. Upon completion of the Block Write, registers 18 and 19 

contain the last address plus one of the 8563 RAM locations in which it was written. 

^ Note that one write cycle follows the initial write operation to register 31; 

i j therefore, the quantity written to register 30 should be one less than the number of 8563 

' ( memory locations in which you want to write. 

n BLOCK COPY 

' { The Block Copy feature copies (reads and writes) data from one section of 8563 RAM 

to another. To copy a block of 8563 RAM: 



1. Place the destination address, where copying in RAM begins, into registers 
18 (high byte) and 19 (low byte). 

2. Wait for the Update Status Ready bit to become high (1). 

3. Set (1) bit 7 of register 24, which selects the Block Copy feature. At this 
point, the 8502 writes the initial source address for the block copy to registers 
32 (high byte) and 33 (low byte). 

4. Place the number of successive memory locations to copy into register 30. 

The 8563 reads the contents of the first source address and writes the data to the 
first destination address. The 8563 RAM addresses are automatically incremented and 
copying continues until the number of memory locations specified by register 30 are copied. 

READING FROM 8563 RAM 

The process of reading from 8563 RAM is the same as reading from a register, except 
you read from the data register, register 31. 

PROGRAMMING THE 8563 CURSOR 

The 80-column cursor is programmable in its image and movement. First, the cursor 
image may be programmed in four different ways. Bits 6 and 5 of register 10 control the 
following four characteristics of the cursor: 



BIT VALUE CHARACTERISTIC 

6 5 

Solid cursor 

1 No visible cursor 

1 Slow cursor blink rate ('/it the frame rate) 
1 1 Fast cursor blink rate (V31 the frame rate) 
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Bits 4 through in register 10 determine the bottom scan line in which the cursor 
definition begins within the 8 scan line cursor character block. Scan line is at the top 
of the cursor character block, while scan line 8 is at the bottom. ] j 

The interrupt-driven screen editor has an indirect location which controls the [J 

cursor programming mode. Location $0A2B in CI 28 RAM is the shadow register which 
controls the different ways to program the 8563 cursor. , , 

Bits 4 through in register 11 specify the top scan line in which the cursor j ( 

definition ends within the 8 scan line cursor character block. Bits 4 through in registers 
10 and 1 1 specify the height of the cursor. These registers enable you to program the 
cursor as a solid block cursor (by default) or as an underlined cursor. 



u 



CURSOR POSITIONING 

Register 14 (high byte) and 15 (low byte) determine the position of the cursor within the 
displayed frame (screen). This register pair indicates the address of the cursor within 
8563 display memory. The address of the cursor can be one that is not in the display 
area of the current frame. If this address is within the address range of the current frame 
(screen), the character position where the cursor is displayed appears in flashing reverse 
video, as do most cursors. 

The interrupt driven screen editor also has an indirect location that controls the .~, 

cursor column and row positioning. Location $0A35 in C128 RAM is the shadow ) 

register for the 8563 cursor column and row selection. ""^ 











>wJ 



The 8563 chip supports a bit-map mode. The resolution of the 80-column bit-map screen ] { 

is 640 by 400 pixels. The 8563 addresses the bytes that make up the bit map across the 
width of the screen, instead of in 8 by 8 character cells as with the VIC chip. 

Bit-map mode is selected by setting bit 7 of register 25. The Kemal initializes r , 

bit 7 to to select text mode. j 

The three main components of an 8563 bit-map display, bit-map data, display ^ 

memory and color, are similar to the VIC chip in some ways but differ in others. For 
example, the VIC has an 8000-byte RAM bit map, in which each bit is assigned an ) / 

individual pixel on the visual screen. Since the 8563 bit map is twice the resolution of the 
VIC screen, it uses twice the memory: 16,000 bytes (a little less than 16K). The 
one-to-one correspondence between bits in memory and pixels on the screen is similar, 
but they are addressed differently. The addresses to access those bits are laid out 
differently in memory. 

Figure 8-25 in chapter 8 illustrates how the VIC bit map is stored in memory. The 
VIC screen stores 8 bytes of the bit-map in the 8 bytes that would normally make up a 
character in character mode. For instance, the first 8 bytes of the visual bit map are 
stored in the first (HOME) character position, which defaults to 8192 ($2000) to 8199 
($2007), or the first eight pixels of the first eight raster rows. The character to the 
immediate right of the HOME position stores the second eight pixels of the first eight 
visual raster rows. The 200 visible VIC screen raster rows are 320 pixels wide. The 200 
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visible 8563 raster rows are 640 pixels wide. Both the VIC and 8563 screens have 
raster rows which are not visible on the screen. This portion is known as the vertical retrace. 
The 8563 screen is stored byte by byte across a raster row. The first eight pixels of 
the first raster row are stored in the first byte of the 8563 bit-map byte, address $0000 in 
8563 RAM. The second eight pixels of the first row are stored in the second byte of the 
bit map ($0001 in 8563 RAM). The third eight pixels are stored in location $0002 and 
so on. The first raster row is stored in the first eighty memory locations in 8563 RAM, 
the second raster row is stored in the second eighty (80-159) 8563 RAM addresses and 
so on. See Figure 10-5 below for an illustration. 



' I 85«3 CHARACTER COLUMNS 

RASTER 

n ROW 1 2 3 4 5 6 7 8 9 10 11. .80 

j I 

' ' 1 $0000 $0001 $0003 $40004$0005 $0006 $0007 $0009 $OOOA$OOOB$OOOC . . . $004F 

2 $0050 $0051 $0052 $0053 $0054 $0055 $0056 $0057 $009F 

m 3 $00A0 

i ! 4 $00F0 



25 $3E30 $3E7F 

Figure rO-5. The Relationship Between 8563 Bit Map Data and Screen Pixels 

The collection of the 640 by 200 pixels on the screen form the image in this way: bits 
that are set (1) enable screen pixels in the foreground color and clear (0) bits take on the 
background color. 

THE BIT-MAP POINTER 

The pointer to the start of the 8563 bit map defaults to the start of display memory at 
8563 RAM location $0000. The display memory start address is contained in registers 
12 (high) byte and 13 (low byte). The contents of this address mark the address of 
the first eight pixels of the top raster row on the 8563 screen (frame). Add an index to 
access successive pixels in successive raster rows. 

Since the full 640-by-200 bit map uses almost all of the 16K available in 8563 
RAM, there is no room available in memory for attributes such as color. 

COLOR ASSIGNMENTS 

The pixel color assignments for the 8563 bit map are based on the value of the bit in 
memory which corresponds to the pixel on the screen. If the value of the bit in memory 
is equal to zero, the pixel is colored in the background color according to the value of 
bits through 3 in 8563 register 26. If the value of the bit in memory corresponding to 
the screen pixel is equal to one, the pixel is assigned the foreground color determined by 
bits 4 through 7 in register 26. 

The full-sized 640-by-200 pixel bit map bit takes up almost the fiill 16K of 8563 RAM. 
You may wonder how you can use the attributes for the corresponding screen locations. 
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01800 


20 


B3 


18 


JSR 


$18B3 


01803 


A2 


19 




LDX 


#S19 


01805 


A9 


80 




LDA 


#S80 


01807 


20 


77 


18 


JSR 


S1877 


0180A 


A9 


20 




LDA 


#S20 


0180C 


85 


FB 




STA 


$FB 


0180E 


A9 


00 




LDA 


#?00 


01810 


85 


FA 




STA 


$FA 


01812 


A2 


12 




LDX 


#S12 


01814 


20 


77 


18 


JSR 


$1877 


01817 


E8 






I NX 




01818 


20 


77 


18 


JSR 


S1877 


0181B 


A9 


00 




LDA 


#500 


0181D 


85 


Bl 




STA 


?B1 


0181F 


A9 


19 




LDA 


#$19 


01821 


85 


93 




STA 


$93 


01823 


A9 


07 




LDA 


#$07 


01825 


85 


9C 




STA 


$9C 


01827 


A9 


27 




LDA 


#$27 








You have two choices: either disable the attributes or reduce the size of your bit 
map by 2000 bytes, then define and enable the attributes. With a full-size bit map, you 
cannot implement the attributes, because there is simply not enough independent 8563 RAM | I 

to do both. If attributes are disabled, the 8563 bit-map screen uses only two colors, as LJ 

specified by the background and foreground color codes in register 26. 

If you decide to reduce the size of the 8563 bit map and you want to implement » , 

the attributes, set bit 6 of register 25 to enable attributes. Then place the high-byte i / 

and low-byte addresses in registers 20 and 21, respectively, to define the start of '~^ 

attribute storage. See the Character Attributes section for more information on attributes. 

u 

THE BIT-MAP FI^ME SIZE 

The size of the bit-map frame defaults to the 640 by 200 raster row dimensions. This \~j 

frame (screen) size may be reduced. See the Register-by-Register Description for details [J 
on altering the size of the visual bit-map image. 

The next section provides an example of a bit-map program in machine language , 

containing a program listing and details about the important routines. i | 



8563 BIT MAP PROGRAM U 

As you know, the 8563 supports bit map mode; however, the BASIC graphics com- i , 

mands are not displayed on the 8563 screen. This section contains a program which i 

transfers the 40-column VIC screen to the 8563 display screen. The screen is still 40 
columns wide, though it provides the vehicle with which to understand how the 8563 bit 
map screen is addressed. For easier programming, more graphics features and general 
functional design use the VIC chip when bit mapping high resolution graphics. The VIC 
chip is principally designed for these purposes. The 8563 is primarily designed for the 
80-character column display capability. i i 

Here's the program listing as it appears in the Machine Language Monitor. Enter \_j 

the Monitor and start entering the program at address $1800. 

W 

u 



u 
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01829 


85 


FE 




STA 


SFE 


0182B 


EA 






NOP 




0182C 


EA 






NOP 




0182D 


A2 


00 




LDX 


#$00 


0182F 


Al 


FA 




LDA 


($FA,X) 


01831 


20 


75 


18 


JSR 


$1875 


01834 


20 


83 


18 


JSR 


$1883 


01837 


EA 






NOP 




01838 


EA 






NOP 




01839 


EA 






NOP 




0183A 


C6 


FE 




DEC 


$FE 


0183C 


DO 


EF 




BNE 


$182D 


0183E 


A5 


Bl 




LDA 


$31 


01840 


DO 


IC 




BNE 


$185E 


01842 


EA 






NOP 




01843 


EA 






NOP 




01844 


EA 






NOP 




01845 


A2 


00 




LDX 


#$00 


01847 


Al 


FA 




LDA 


($FA,X) 


01849 


20 


75 


18 


JSR 


$1875 


0184C 


20 


8F 


18 


JSR 


$188F 


0184F 


20 


9B 


18 


JSR 


$189B 


01852 


C6 


9C 




DEC 


$9C 


01854 


DO 


Dl 




BNE 


$1827 


01856 


A9 


01 




LDA 


#?01 


01858 


85 


Bl 




STA 


$B1 


0185A 


4C 


27 


18 


JMP 


$1827 


0185D 


EA 






NOP 




0185E 


A9 


00 




LDA 


#$00 


01860 


85 


Bl 




STA 


$B1 


01862 


A2 


00 




LDX 


#$00 


01864 


Al 


FA 




LDA 


($FA,X) 


01866 


20 


75 


18 


JSR 


$1875 


01869 


20 


8F 


18 


JSR 


$188F 


0186C 


20 


A9 


18 


JSR 


$18A9 


0186F 


C6 


9B 




DEC 


$9B 


01871 


DO 


BO 




BNE 


$1823 


01873 


00 






BRK 




01874 


00 






BRK 




01875 


A2 


IF 




LDX 


#$1F 


01877 


8E 


00 


D6 


STX 


$D600 


0187A 


2C 


00 


D6 


BIT 


$D600 


0187D 


10 


FB 




BPL 


$187A 


0187F 


8D 


01 


D6 


STA 


$D601 


01882 


60 






RTS 




01883 


18 






CLC 




01884 


A5 


FA 




LDA 


$FA 


01886 


69 


08 




ADC 


#S08 


01888 


85 


FA 




STA 


$FA 


0188A 


90 


02 




BCC 


$188E 


0188C 


E6 


FB 




INC 


$FB 


0188E 


60 






RTS 




0188F 


AO 


28 




LDY 


#$28 


01891 


A9 


00 




LDA 


#$00 


01893 


20 


75 


18 


JSR 


S1875 


01896 


88 






DEY 




01897 


DO 


F8 




BNE 


$1891 


01899 


60 






RTS 




0189A 


EA 






NOP 




0189B 


38 






SEC 




0189C 


A5 


FB 




LDA 


$FB 


0189E 


E9 


01 




SBC 


#$01 


018A0 


85 


FB 




STA 


$FB 


018A2 


A5 


FA 




LDA 


$FA 


018A4 


E9 


37 




SBC 


#$37 


018A6 


85 


FA 




STA 


$FA 


018A8 


60 






RTS 




018A9 


E6 


FA 




INC 


$FA 


018AB 


DO 


02 




BNE 


$18AF 


01 SAD 


E6 


FB 




INC 


$FB 
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018AF 60 RTS 

018B0 EA NOP 

018B1 EA NOP 

018B2 EA NOP 

018B3 A9 00 LDA #$00 

018B5 85 FC STA SFC 

018B7 A9 3F LDA #$3F 

018B9 85 FD STA SFD 

018BB A2 19 LDX #$19 

018BD A9 80 LDA #$80 

018BF 20 77 18 JSR $1877 

018C2 EA NOP 

018C3 EA NOP 

018C4 A9 00 LDA #$00 

018C6 A2 12 LDX #$12 

018C8 20 77 18 JSR $1877 

018CB E8 INX 

018CC EA NOP 

018CD EA NOP 

018CE 20 77 18 JSR $1877 

018D1 A9 00 LDA #$00 
018D3 

018D6 C6 FC DEC $FC 

018D8 DO F7 BNE $18D1 

018DA C6 FD DEC $FD 

018DC DO F3 BNE $18D1 

018DE 60 RTS 



li 
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A9 00 LDA #$00 ! 1 

20 75 18 JSR $1875 (_) 



The instructions in this explanation are referenced by the memory addresses that 
appear in the left column of the machine language monitor output as in the other j j 

machine language program explanations. ij 

The first instruction (J$R $18B3) jumps to a subroutine to clear the bit map (8563) 
screen. / • 

The next sequence of instructions ($1803-$1809) set bit 7 of 8563 register 25 to j 

select bit map mode. This bit defaults to for text display. The subroutine starting at 
$1877 is the familiar register write routine you have seen earlier in the chapter. Notice 
that if the subroutine had started at location $1875, it would have written to 8563 RAM | | 

instead of an 8563 register. This routine is called to do so later in the program. Uj 

The trick to the success of this program is addressing both the VIC screen and the 
8563 screen correctly. The second sequence of instructions ($180A-$1816) define the 
high byte of the 16-bit address for the start of both the VIC and 8563 screens. First the 
X register is loaded with the value 18 ($12) which selects 8563 register 18, the 8563 
RAM address high pointer. The accumulator is loaded with the value $20, which is 
stored in location $FB, the VIC bit map pointer (high byte). Now the accumulator is 
cleared to zero and the write register subroutine places the value zero into the 8563 bit ^ 

map (high byte) pointer. 

The instructions $1817 through $181 A perform the same operation for the low i' 

byte of both the VIC and 8563 bit map pointers. [J 

The instructions between $1820 and $1827 initialize the variables $FC, $FD, $B1 
and $9C to zero. The variables $FC and $FD are the low and high byte pointers for the 
8563 bit map RAM addresses. The variable $B1 is the column counter for the VIC 
screen. The variable $9C is the counter that keeps track of how many addresses to skip 
in 8563 RAM. This is explained later in the program. 
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Here's where a major difference between the two video chips becomes important — 
the way the bit map corresponds to the image on the screen. As you know, the VIC 
, I screen stores eight rows of 8 pixels each to make up one character cell. Each row of the 

i i eight pixels in a character on the screen are stored consecutively in memory. For 

example, the HOME character position is stored in default locations $2000 through 
$2007 for the bit map. The next character position (as if the display was standard text) 
to the right of the HOME Position is stored between $2008 and $2015. So the first 
character row is stored between $2000 and $2A00 ($2000 plus (8*8) * 40 =2560). This 
is represented graphically in the preceding section (Figure 10-5). 

On the other hand, the 8563 stores a bit map across raster rows on the screen. 

Each set of eight pixels of a raster row is stored in a memory location in 8563 RAM 

starting at $0000. For example, the first raster row is stored in locations $0000 through 

p $0050, one location for each group of eight pixels. The 8563 screen is 640 pixels across; 

' I therefore each row needs 80 bytes of storage in 8563 RAM. 

Now you see how the two bit maps are addressed differently. To fiiUy understand 
r^ how this program gets data from the VIC bit map and places it in the correct spot on the 

( j 8563 bit map, this algorithm is provided. The actual instructions to perform these steps 

are added later. Here's the general scheme you need to follow: 

n 

j I 1. Start at the beginning of both the VIC and 8563 bit map locations. 

2. Get a VIC bit map byte. 
_ 3. Store it in the 8563 bit map. 

4. Increment the VIC bit map pointer 8 times (the 8563 pointer increments itself 
after a write). 

5. Do steps 2, 3 and 4 thirty-nine times. 



/ i At this point, you have just transferred the first raster row of the VIC bit map onto 

the 8563 bit map. 

'; \ 6. After each raster row is transferred, subtract 3 1 1 from the VIC bit map pointer. 

This is done 7 times. On the eighth time, the VIC bit map pointer is 

r-, incremented by 1 to get the to the start of the next VIC character cell. 

7. Perform 40 blank write operations (write zeros to the 40 blank colunms) to 
get to the beginning of an 8563 raster row. Remember, the 8563 bit map 
pointer must be relative to the VIC screen bit map pointer. 



If the VIC column counter equals 39, increment the 8563 bit map pointer 41 
times to place its relative position at the start of a new character row according to the 
VIC bit map. 

8. Now repeat the process 25 times, once for each character row. 
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SCROLLING THE 8563 SCREEN 

The 8563 has a feature that allows the screen to scroll smoothly either vertically (up or 
down) or horizontally (left or right). The 8563 scrolling feature can be thought of as a 
small virtual screen window which is displayed on a portion of a full size 80-by-25 
character screen. The virtual screen is only visible through the window you define at the 
specified position of the full-sized screen. Both screens however do exist in the 8563 
character RAM storage locations. 



Li 



In the program, as discussed, the instructions in $180A through $181A start the '-' 

VIC and 8563 bit maps at locations $2000 and $0000 respectively. All these instructions 
encompass step 1 of the algorithm. ) i 

The instructions that perform step 2 of the algorithm are stored at locations Li 

$182D-$1830. 

Step 3 stores the VIC bit map byte at the 8563 bit map position and is performed j j 

by the instruction $1831 and the subroutine stored between $1875 and $1882. This Li 

subroutine writes the value stored in the accumulator into the appropriate address in 
8563 RAM as specified by the contents of 8563 registers 18 ($12) and 19 ($13). > , 

The instructions stored at $183 A through $183D perform the fourth step of the I | 

algorithm. 

The stored in $1883 through $188E update the VIC bit map pointer by 8. 

Steps 2, 3 and 4 are performed while the pixel row counter in $9C is less than 
seven. If it is less than seven, the next byte of the VIC bit map is loaded and stored into 
the 8563 bit map. 

Step 6 is contained in the subroutine starting at ($189B). This decrements the VIC 1 I 

bit map pointer by 311 locations. U 

Step 7 of the algorithm is contained in the subroutine stored in locations $188F 
through $1899. ^", 

Finally, step 8 of the algorithm is performed by the instructions $186F through jj 

$1872. 

This program allows you to transfer one bit map to the other, but leaves the VIC (^ 

bit map as 40 columns. Expand on the algorithm in this section and center the bit map 1 

on the 80-column screen. Write a routine that proportionally spaces the 40-column bit 
map and places it on the entire 80-coIumn screen. Also add a routine that clears the 
other half of the 80-column bit map. Add these routines to any business application, and 
you'll have a valuable business tool which you can use completely within the 8563 chip 
that display your character and bit map data. 
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VERTICAL SCROLLING 

Scrolling in the vertical direction is easier than scrolling horizontally. The general 
algorithm to scroll vertically is as follows: 

1. Set the default start of the character RAM storage to $2000 in 8563 RAM. 
This is done through writing to (or using the default contents of) registers 
12 ($0C) and 13 ($0D). Now location $2000 in 8563 RAM marks the start 
of the first character in the upper left comer of display memory (the HOME 
position). 

At this point, the size of the screen is 80-by-25 and the screen RAM 
locations are from $2000 through $27CF in 8563 RAM. Therefore, the first 
80 bytes store the first 80 characters in the top row of the 8563 screen. 

2. Now add 80 ($50) to the low byte of the display RAM Pointer, register 13. 
Now the second 80 bytes of the display RAM memory are displayed as the 
first character row. The screen is now defined by locations $2050 through 
$28 IF in 8563 memory. This moves the characters up one character row. The 
"old" first character row has moved off the top of the screen and the "new" 
character row has moved onto the last character row of the screen from a 

n previously non-visible range in display area. The new character row should be 

I I defined in 8563 RAM before it is moved onto the screen as the last character 

row. 
r^ 3. Though this moves an entire character row of display RAM up by one row, 

the movement is sudden, abrupt and not smooth. The 8563 allows smooth 
scrolling to occur vertically, through the lower four bits of register 24 ($18) in 
the 8563. 

To scroll smoothly one scan line at a time, write the value 1 to register 
24. This moves the entire screen up by one scan line. The first previously 
visible scan line is now off screen at the top and a new scan line is scrolled 
from an off screen location from the bottom onto the last visible scan line of 
the screen. 

4. To scroll subsequent scan lines, increment the value of the lower four bits of 
n register 24. By incrementing this value to 2, the entire screen is smoothly scrolled 
( \ an additional scan line. 

5. Continue to increment the value in register 24 until the value equals the value 
stored in the lower four bits of register 9, the total number of vertical scan 
lines of a character. Once these values are equal, only the bottom scan line of 
the first character row is visible at the top of the screen, and all but the 
last scan line of the newly scrolled data is visible at the bottom of the screen. 

6. To continue to scroll, reset the value in the lower four bits of register 24 to 
zero and add 80 more locations to the contents of the display RAM pointer as 
you did in step 2. 

If you plan to use attributes, you must increase the value of the attribute 
start pointer also to keep up with the display RAM pointer. 
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HORIZONTAL SCROLLING 

Horizontal scrolling is more complex than vertical scrolling. First, the Display RAM 
memory must be set up to match the "virtual" screen size. If the "virtual" screen is 
132 characters wide, then the Display RAM memory must be organized as if 132 
characters were to be displayed, even if only 80 horizontal characters will be displayed 
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01800 A2 OC LDX #SOC 

01802 A9 20 LDA #$20 

01804 85 FB STA 5FB 

01806 20 60 18 JSR $1860 

01809 E8 INX ) / 

0180A A9 00 LDA #$00 | f 

0180C 85 FA STA $FA ^-J 

0180E 20 60 18 JSR $1860 

01811 EA NOP 

01812 A2 18 LDX #$18 
01814 A9 01 LDA #$01 

01816 A8 TAY L_i 

01817 20 60 18 JSR $1860 
0181A EA NOP 

0181B C8 INY , , 

0181C 98 TYA 

0181D CO 08 CPY #$08 M 

0181F DO F6 BNE $1817 

01821 EA NOP 

01822 EA NOP 

01823 A9 00 LDA #$00 1 ', 
01825 20 60 18 JSR $1860 
01828 AO 00 LDY #$00 
0182A E6 FA INC $FA 
0182C DO 02 BNE $1830 
0182E E6 FB INC $FB 

01830 C8 INY 

01831 CO 50 CPY #$50 
01833 DO F5 BNE $182A 
01835 A2 OC LDX #$0C 
01837 A5 FB LDA $FB 
01839 20 60 18 JSR $1860 
0183C E8 INX 
0183D A5 FA LDA $FA 
0183F 20 60 18 JSR $1860 
01842 A9 00 LDA #?00 



u 



II 



01844 85 FD STA $FD 

01846 A9 00 LDA #$00 

01848 85 FC STA $FC ^~' 

0184A E6 FC INC $FC 

0184C DO FC BNE $184A 

0184E E6 FD INC $FD | J 

01850 A5 FD LDA $FD ! ■ 

01852 C9 AO CMP #$A0 ^-' 

01854 DO FO BNE $1846 

01856 4C 12 18 JMP $1812 

0185 9 EA NOP 

0185A EA NOP 

0185B EA NOP 

0185C EA NOP 

0185D EA NOP 

0185E EA NOP i, j 

0185F EA NOP < 

01860 8E 00 06 STX $D600 LJ 

01863 2C 00 D6 BIT $D600 

01866 10 FB BPL $1863 

01868 8D 01 D6 STA $D601 

0186B 60 RTS 
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in the 8563 "window." This means that to display a window of 25 rows of 80 
characters of a virtual screen of width 132 characters, the Display RAM memory must 
have at least 3300 (132 x 25) memory locations and the same number of attributes. 

To display a horizontal "window" of 80 characters, the 8563 must first read the 
first 80 display memory locations and attributes from the first 132-character row, and 
then "skip" the next 52 (132-80) and proceed to read the next 80 pointers and attributes 
from the second 132-character row. The amount of the "skip" must be written to R27. 
In this case "52" is written to R27 at system initialization. 

When horizontal scrolling is not used, a "zero" written to R27 will cause the 
8563 to skip no display memory locations or attributes, allowing the "virtual" screen in 
Display RAM memory to be the same width as the 8563 window. 

Now that the 8563 has been set up to view a window 80 characters wide out of a 
virtual screen of 132 characters wide, horizontal scrolling may occur by modifying the 
address in R12/R13 (DISPLAY START ADDRESS) and R20/R21 (ATTRIBUTE START 
ADDRESS). Increasing these addresses by one will scroll the entire screen "left" one 
|— ) character. The first character of each character row will be scrolled "off" the left side 

of the screen, all characters on the screen will be moved one space to the left, and one 
extra character will be scrolled onto the right side of the screen. Simple manipulation of 
the address in R12/R13 and R20/R21 will scroll the window to the left or right. 

SMOOTH HORIZONTAL SCROLLING 

The 8563 has the ability to scroll smoothly in the horizontal direction. Horizontal 
smooth scrolling moves all characters on the screen the desired number of pixels to the 
"left," up to the width of one character. Before horizontal smooth scrolling can occur, 
the 8563 must have something to scroll "onto" the right side of the screen, so R27 must 
be greater than zero. This sets up a virtual screen at least one character greater than the 
displayed screen. 

The screen is scrolled left by one pixel by changing the contents of R25(3-0) to 
"one" and increasing the contents of R22(3-0) by one. Both registers must be changed 
to scroll horizontally. 

': i The number in R25(3-0) and R22(3-0) may be increased, increasing the number 

of pixels scrolled, until R25(3-0) equals R22(7^). This is the maximum amount of 

r^ horizontal smooth scrolling allowed. At this point, only one (the right) pixel will exist 

j \ for the first character of each character row and the last character will have scrolled onto 

the row with only the one (the right) pixel still not visible. To scroll further, the CPU 

must change R25(3-0) back to zero and increase RI2/R13 (DISPLAY START AD- 

n DRESS) and R20/R21 (ATTRIBUTE START ADDRESS) each by one to scroll hori- 

• ' zontally by one character. This sequence will have smooth-scrolled left by one character. 
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REGISTER-BY-REGISTER 
DESCRIPTION 



U 

u 

This section describes each 8563 register in detail by register number. The significant 
bits are isolated and explained separately. j 1 

The conventions used in the register descriptions are as follows: Li 



Rn (msb-lsb) 



/ 



The R stands for "register." The letter n represents the register number, ranging N 

from through 36. The msb stands for "most significant bit" in that particular 
description. Often the most significant bit is assumed to be bit 7; however, in this 
discussion, bit 7 is not always the most significant. I ; 

The notation Isb stands for "least significant bit" in the particular register ^ 

description. Generally, the least significant bit is assumed to be 0; however, in this 
description is not always the least significant. \ 

If a single bit number is enclosed in parentheses, then this is the only bit explained L 

for that particular function. 

Consult this section as a quick reference. See the main body of the chapter for , ^ 

additional background on programming the 80-column display. j j 

RO HORIZONTAL TOTAL 

The number of characters, minus 1, between successive horizontal sync pulses. This \ 

number includes the displayed part of a character row, the horizontal border and the '— ' 

blanking interval during horizontal sync pulses. 

Rl HORIZONTAL DISPLAYED [J 

The number of characters displayed on each character row. This number sets the width 

of the displayed part of the character row. ; , 

i J 

R2 HORIZONTAL SYNC POSITION "^ 

The number of characters from the beginning of the displayed part of a character row to , 

the start of the horizontal sync pulse. This register controls the horizontal position of the , j 

text on the CRT screen. This number should be greater than the number in Rl '~-' 
(horizontal displayed). 

R3(3-0) HORIZONTAL SYNC WIDTH U 

The width of the horizontal sync pulse in characters, plus 1. 

R3(7-4) VERTICAL SYNC WIDTH jj 

The width of the vertical sync pulse in scan lines. This number sets the duration of the 
vertical sync pulse, which may extend past the end of the current frame into the next 
frame. In the interlaced sync and video mode, this register should be programmed with a 
value equal to twice the number of scan lines desired. '— 
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R4 VERTICAL TOTAL 

The number of character rows, minus 1, between successive vertical sync pulses. This 
number includes the displayed rows, vertical border and the blanking interval during the 
vertical sync pulse and determines the vertical sync rate. 

R5(4-0) VERTICAL TOTAL ADJUST 

The number of scan lines added to the end of the frame for fine adjustment of the 

vertical sync rate. In the interlaced sync and video mode, this register should be 
f—, programmed with a value equal to twice the number of scan lines desired. 

i I 

R6 VERTICAL DISPLAYED 

The number of character rows displayed in a frame. This number sets the height of the 
'P' displayed part of the frame. 

I ! 

R7 VERTICAL SYNC POSITION 
I—) The number of character rows, plus 1, from the first displayed character row to the 

I I start of the vertical sync pulse. This number should be greater than the number in R6 

(vertical displayed). 

n R8(l-0) INTERLACE MODE CONTROL 

' There are three raster-scan display modes: non-interlaced, interlaced sync, and interlaced 

sync and video. The non-interlaced mode has been described above. In this mode, each 
P scan line is refreshed at the vertical sync rate. This mode is selected by setting R8(l-0) 

i 1 equal to 00 or 10. 

In the interlaced sync mode [R8(l-0) = 01], even and odd fields alternate to 
fm, generate frames. The same information is displayed in both odd and even fields but the 

! j vertical sync timing causes the scan lines in the odd fields to be displaced from those in 

' the even fields by one-half scan line. The spaces between adjacent scan lines are filled, 

resulting in a higher-quality character on monitors designed to receive interlaced video. 
p In the interlaced sync and video mode [R8(l-0) = 11] even and odd fields 

' i alternate to generate frames. Odd fields display odd scan lines, and even fields display 

even scan lines. This doubles the vertical character density on the screen. To display 
p! twice as many character rows, the user must re-initialize the 8563 registers. In this 

j j mode, the vertical sync width [R3(7-4)] and the vertical total adjust [R5(4-0)] should be 

programmed with even values. The duration of each of these events (in scan lines) will 

be one half the value programmed into the registers. 

! * R9(4-0) CHARACTER TOTAL, VERTICAL 

The number of scan lines, minus 1, in a character. This number includes the displayed 
p part of a character and the vertical intercharacter spacing below the displayed part. This 

! I register sets the vertical dimension of a character and the vertical dimension of a 

character row. 
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R 1 0(6-5) CURSOR MODE 

The cursor can be programmed to four different modes by programming R10(6-5) to a 
00 (solid cursor), 01 (no cursor), 10 (cursor blinking at one sixteenth the frame rate), or 
1 1 (cursor blinking at one thirty-second the frame rate). 

Rl 1(4-0) CURSOR END SCAN LINE 

The number of the last (bottom) scan line of the reverse- video cursor, plus 1. 



u 



Rl 0(4-0) CURSOR START SCAN LINE 

The number of the first (top) scan line of the reverse-video cursor. The number refers 

to the first (top) scan line of the character. This register and register 1 1 (below) define I j 

the cursor height, and can create a variety of effects, from a block cursor to an underline ^ 

cursor. 



! I 
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RI2, Rl 3 DISPLAY START ADDRESS (HIGH, LOW) 

The address of the first (left) 8 pixels of the top scan line of the frame is defined by R12 
and R 13. The most significant 8 bits are in R 12, the least significant in R13. These set 
the complete 16-bit address for the first 8 pixels. The address of subsequent sets of 8 
pixels on that scan line are incremented from the previous address. The bit-mapped pixel 
data for a scan line is fetched from adjacent memory locations. A frame of 640 
horizontal by 200 vertical pixels will use 16,000 bytes of display 8563 RAM memory 
locations (R12, R13) through (R12, R13 + 15999). 

The bit map attributes are a set of Display RAM bytes, each of which '> I 

corresponds to a character position on the frame. The 8-bit attribute defines additional [J 

characteristics of the character area at that position on the frame. These characteristics 
(attributes) are as follows: Bits 3-0 are foreground R, G, B and I, respectively. Bits 7-4 , , 

are background R, G, B and I, respectively. For a frame of i rows of j characters each, j 1 

the first j attributes will define the attributes for the first (top) character row, and (i X j) ^ 

attributes will need to be defined in display 8563 RAM. For a bit-mapped frame of 25 
characters high and 80 characters wide, 2000 attributes will be needed. 1 I 



u 



RI2, RI3 DISPLAY START ADDRESS (HIGH, LOW) 

The address for the pointer of the first (top-left) character of the frame is defined in R12 
and R13. The most significant eight bits is in R12, the least significant in R13. These jj 

set the complete 16-bit address for that first pointer. The address of pointers of 
subsequent characters are incremented from the previous address, so horizontally adja- 
cent characters have pointers in adjacent memory locations. A frame of 25 character 1 j 
rows of 80 characters each will use 2000 pointers of display 8563 RAM memory ^ 
locations (R12/13) through (R12/13 -I- 1999). 

RI4, RI5 CURSOR POSITION J 

The position of the cursor is set by R14 and R15. These two registers contain the 16-bit 

address of the cursor. R14 is the most significant byte, R15 the least significant. If the 

address of R14/R15 is the address of a character within the displayed part of the frame, j 

then that character will be displayed in reverse video for those scan lines determined by ^ 
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R10(4-0) and Rl 1(4-0). These registers allow the 8563 to be programmed for a 
reverse- video "block" cursor, or for an "underline" cursor. The location of the cursor 
can be changed by changing the contents of registers R14 and R15. 

RI6, RI7 LIGHT PEN VERTICAL, HORIZONTAL 

The 8563 supports a light pen function. When the LPEN input pin transitions from a low 

to high, the 8563 latches the current vertical and horizontal character counts in the two 
' ' light pen registers. The vertical count is latched in R16. LPEN transitions that occur 

during the row at the top of the frame will latch a 1 in R16. Transitions on subsequent 
n rows will latch 2, 3, etc. The horizontal count is latched in R17. LPEN transitions that 

I i occur during the leftmost character column will latch an 8. Transitions on subsequent 

columns will latch 9, 10, etc. The condition of the light pen registers is latched in bit 6 of 

the status register. If 0, the light pen registers have not been latched and contain invalid 
j I data. If 1, the registers contain valid latched data. A CPU read of R16 or R17 resets 

the Status Register bit. 

n READ AND WRITE DISPLAY 

8563 RAM MEMORY 

n RI8, RI9 UPDATE LOCATION 

R3I CPU DATA 

The CPU communicates to the 8563 RAM memory via address and data registers in 
the 8563. For the CPU to read a memory location, it must place that address in registers 

i i R18 (most significant byte) and R19 (least significant). The 8563 responds by executing 

a read of that memory location and placing that data into R31 , which the CPU may then 

|— 1 read. During the time that the "read" is pending and data is not yet valid in R31, the 

1 I Update Ready bit of the status register (bit 7) will be 0. Upon completion of the read 

cycle, data will be valid in R31 and the bit will be 1. When the CPU reads the data in 

R31, the 8563 increments the address in R18/R19 and performs a read of that address. 

This allows the CPU to read successive memory locations without repeatedly changing 

the addresses in R18/R19. 

For the CPU to write data to a memory location, the address must be written to 
P R18/R19 as in a "read" described above. Following the automatic read and after the 

i ! Update Ready bit is a 1, the CPU should write the desired data to R31. The 8563 then 

writes the data to 8563 Memory at the address defined by R18/R19, increments the 

~* address in R18/R19, reads the data from the incremented memory location and places it 

I in R31. The 8563 then sets the Update Ready bit to a 1. At all times, if the Update 

Ready bit is a 0, then CPU access to 8563 memory is pending. Additional access of R18, 

R19 or R31 should be avoided until the Update Ready bit is a 1. 

R20, R2I ATTRIBUTE START ADDRESS (HIGH, LOW) 

The address for the attribute of the first (top-left) character of the frame is defined in 
R20 and R21. The most significant 8 bits is in R20, the least significant in R21. These 
set the complete 16-bit address for that first attribute. The address of attributes of 
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R24(4-0) VERTICAL SMOOTH SCROLL 

The sudden scroll of an entire character row is too abrupt a change for some applica- 
tions. The 8563 supports a method of vertically scrolling the screen one scan line at a 
time, up to one full character row. This is called vertical smooth scroll. This operates 
along with vertical scrolling to allow the screen to be scrolled up or down smoothly for 
as many character rows as desired. 

To scroll the screen one scan line 'up' vertically, the CPU should write a 1 to 
R24(4-0). This will skip the first scan line of the first character row. The first character 
row will then begin with the second scan line, moving it 'up' one scan line. All 
character rows on the frame will be moved 'up' one scan line also. At the bottom of the 
Frame, one additional scan line will be displayed of a 'new' character row. This will 
actually display parts of "N + 1" character rows instead of the standard N. 



\ ! 



subsequent characters are incremented from the previous address, so horizontally adjacent 
characters have attributes in adjacent memory locations. A frame of 25 character rows of 
80 characters each will use 2000 attributes at display 8563 RAM memory locations 
(R20/R21) through (R20/R21 + 1999). 

R22(3-0) CHARACTER DISPLAYED, HORIZONTAL 

This number sets the width of the displayed part of the character, and defines the 
horizontal intercharacter spacing to the right of the displayed part. 

If the defined character is to have no horizontal intercharacter spacing, then 
R22(3-0) should be initialized with a value equal to (the value of R22(7-4) plus 1). This j i 

value may remain constant even with the use of horizontal smooth scrolling. LI 

If the defined character is to have horizontal intercharacter spacing, then R22(3-0) 
should be initialized with a value equal to the number of pixels (horizontal) in the displayed i i 

part of a character, minus 1. In this case, the value of R22(3-0) must be changed along M 

with R25(3-0) to implement horizontal smooth scrolling. 

In the pixel double-width mode, the value written to R22(3-0) should be 1 larger 
than the numbers described above. } I 

R22(7-4) CHARACTER TOTAL, HORIZONTAL 

The number of pixels (horizontal) in a character, minus 1 . This number includes the I 

displayed part of a character and the horizontal intercharacter spacing to the right of [J 
the displayed part. This register sets the horizontal dimension of a character. 

In the pixel double- width mode , the value written to R22(7^) should be the number of ^ | 

pixels (horizontal) in a character. Do not subtract 1 from the value in this mode. I 

R23(4->0) CHARACTER DISPLAYED, VERTICAL 

The number of scan lines, minus 1, of the displayed part of a character. This number I 

sets the height of the displayed part of the character, and defines the vertical intercharacter L> 

spacing below the displayed part. 

R23(4-0) can be equal to or less than R9(4-0). If they are equal, then the | 

displayed part of the character is equal to the total character, and the entire character is J 

displayed, with no vertical intercharacter spacing. 
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The number in R24(4-0) can be increased, increasing the number of scan lines 
scrolled, until R24(4-0) equals R9(4-0). This is the maximum amount of smooth scroll 
allowed. At this point, only one (the bottom) scan line will exist for the first character 
row and the last character row will have scrolled onto the frame with only the last scan 
line not visible. To scroll further, the CPU must change R24(4-0) back to 0, and 
increase R12/R13 (display start address) and R20/R21 (attribute start address) to scroll 
vertically by one character row. This sequence will have smooth scrolled by one 
character row. 

R24(5) CHAI^CTER BLINK RATE 

When attributes are enabled, the attribute byte for each character contains a bit that 
controls the blinking of that character. The rate at which the characters blink is 
determined by R24(5). If this bit is a 0, then the character blink rate is one-sixteenth of 
the frame rate, if 1, then one thirty-second of the frame rate. 

R24(6) REVERSE SCREEN 

The complete screen can be reversed (foreground and background colors reversed) by 
changing R24(6). With this bit 0, the screen will be displayed with normal foreground/ 
background colors. A 1 will reverse the foreground and background colors for each 
character on the screen. This reversal will re-reverse any character normally reversed by 
the cursor and/or the individual character reverse attribute. 

R24(7) BLOCK COPY 
R30 WORD COUNT 

To further improve the speed at which the CPU can manipulate 8563 memory, two 
additional features have been added to the 8563: Block Write and Block Copy. Block 
Write is an extension of the CPU write cycle except that Block Write writes the same 
data to more than one successive memory location. This operation is set up by writing 
the initial address to R18/R19, waiting for the Update Ready Status bit to be 1, writing 
the data to R31 and again waiting for the Update Ready Status bit to be 1. This is the 
same as CPU write (above). The CPU must then write a to R24(7) selecting the Block 
Write mode, then write to R30 the number of successive memory locations the 8563 
should write. Following the write to R30, the 8563 will initiate one or more write cycles 
to 8563 memory, writing the data in R31 to successive memory locations. The contents 
of R18/R19 will increment with the addresses being written. After the Block Writes are 
completed, R18/R19 will contain the address following the last memory location written. 



NOTE: One write cycle will follow the initial write of data to R31, so 
the quantity written to R30 should be one less than the total number of 
memory locations desired to be written. 



R25(3-0) SMOOTH HORIZONTAL SCROLL 

The 8563 has the ability to scroll smoothly in the horizontal direction. Horizontal 
smooth scrolling moves all characters on the screen to the 'left' the desired number of 
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pixels, up to the width of one character. Before horizontal smooth scrolling can occur, 

the 8563 must have something to scroll 'onto' the right side of the screen, so R27 must 

be greater than 0. This sets up a virtual screen at least one character greater than the j I 

displayed screen. |_l 

An unscrolled screen is obtained with the value of R25(3-0) equal to the value of 
R22(7-4) (character total, horizontal). The screen is scrolled left by one pixel by , 

decreasing the contents of R25(3-0) by 1 . Additional scrolling occurs with decreasing 
values programmed. Maximum scrolling is achieved with a value of in R25(3-0). At ^ 

this point, only one (the right) pixel will exist for the first character of each character 
row and the last character will have scrolled onto the row with only one (the right) pixel I 

still not visible. To scroll further, the CPU must change R25(3-0) back to its maximum U 

value and increase R12/R13 (Display Start Address) and R20/R21 (Attribute Start 
Address) each by 1 to scroll horizontally by one character. This sequence will have i i 

smooth scrolled left by one character. M 

If the character has any nondisplayed pixels {R22(3-0) less than [R22(7-4) plus 
one]} then the value of R22(3-0) (character displayed, horizontal) must be changed 
along with R25(3-0) for horizontal scrolling. The value of R22(3-0) should be equal to 
[(the number of horizontal pixels in the displayed part of a character) plus (the value of ^ 

R25(3-0), horizontal smooth scroll)] modulo [(the value of R22(7-4), character total, 
horizontal) plus 1]. In this case both registers R25(3-0) and R22(3-0) must be changed I 

to scroll horizontally. J 

For example, for a character 8 pixels wide with 5 pixels wide displayed: 



u 



There are two different versions of the 8563 chip (80-column RGBI) in produc- 
tion, requiring slightly different register initialization values. , 

The difference between the 8563-R7A and subsequent revisions (8563-R8 and 
8563-R9) is in the horizontal smooth scroll feature, represented by bits 0-3 of register 
25. Even if this feature is not utilized, the correct value must be placed into this register 
for a normal 80-column display. Software designed specifically for 8563-R7As will I 

exhibit a problem with the leftmost side of the display when run on a system with R8s or L 

R9s, and software designed specifically for 8563-R8s and R9s will exhibit a problem 
with the rightmost side of the display when run on a system with R7A. To run correctly 
on any system, the software must initialize register 25 with the correct data for the L 

u 



n 



n 



PROGRAMMING THE 80-COLUMN (8563) CHIP 331 



n 
n 
n 
n 

n 
n 



particular 8563 version in the system. The 8563 version can be easily ascertained 
through software by reading the 8563 status register, located at $D600 in I/O memory. 
Bits 0-2 contain the version number. Refer to the table below for the actual data to be 
used. 



8563 rev version ($D600) register 25 value 

7A $40 

8 1 $47 

9 1 $47 



This situation does not directly affect software which utilizes the resident CI 28 
operating system (Kemal). The Kemal correctly determines which version of the 8563 is 
present and initializes it accordingly. Software which relies on the Kemal lOINIT 
routine to accomplish this initialization will not have any problems. Software which 
performs the initialization itself, or alters the contents of the affected register, may 
exhibit the 80-column display anomalies described above, but will otherwise function 
normally. 

R25(5) PIXEL DOUBLE WIDTH 

A change from an 80-column frame to a 40-column frame requires the registers of the 
8563 to be initialized differently and requires a different pixel rate. To simplify this 
change, a control bit on the 8563 causes the DCLK input signal to be divided by 2. If 
R25(4) is a 0, then the pixel width is one DCLK period. If it is a 1, then the pixel width 
is two DCLK periods and the internal character clock period is twice the normal period. 
The AC timing is the same as normal. The 8563 RAM bus cycles occur at half the 
normal rate, with the "idle" time spent with RAS and CAS "high." Note that the 
contents of the horizontal initialization registers, and the contents of R22(7-4) and 
R22(3-0) must be initialized with different values in this mode. 

R25(5) SEMIGRAPHIC MODE 

The displayed part of a character is limited to 8 pixels wide owing to the width of the 
Display Data Bus (DD0-DD7). Low-resolution graphics regularly use a "block-graphics" 
character set that may exceed 8 pixels in width. The 8563 allows this in a limited way 
by allowing the last displayed pixel of a character to be repeated in the horizontal 
intercharacter space, which is normally forced to the background color. If the control bit 
R25(5) (semigraphic mode) is a 0, then normal character operation occurs. If it is a 1 , 
then semigraphics operation occurs, allowing characters to extend into the horizontal 
intercharacter space, touching the next character. 

R25(6) ATTRIBUTE ENABLE 

In some applications, attributes are not necessary. In these cases, the amount of 8563 
RAM memory used by the attributes may be excessive, so the 8563 has a control bit to 



332 COMMODORE 128 



u 



U 
U 

y 



disable attribute usage. If R25(6) is a 0, then attributes will not be fetched by the 8563 
and the RAM memory may be used for other purposes. In this case, no character may be 
underlined, individually reversed or blinked. Only one character set of 256 characters 
may be used. The foreground color of all characters will be the same and will be 
determined by R26(7-4). The background color will still be set by R26(3-0). If R25(6) 
is a 1 , then attributes will be used normally. 

R25(7) MODE SELECT (Text/Bit Map) 

The 8563 is primarily a text display device, but it does support a limited bit-mapped 

graphics mode. In the text mode, the displayed frame is an array of characters, each 

with a unique pointer to reference the character, and an attribute to define additional 

display characteristics. In the bit-mapped mode each pixel is controlled by a unique bit 

in 8563 RAM memory. For text operation, bit 7 is initialized to a 0; for bit-mapped j 

operation, set bit 7. Refer to the Bit-Mapping the 80-column Display section in this J 

chapter for more information. 

R26(3-0) BACKGROUND R, G, B, I 

In all cases, the background color is determined by R26(3-0). The borders surrounding '-^ 

the screen and the vertical and horizontal intercharacter spaces are displayed at the 
background color. 

R26(7-4) FOREGROUND R, G, B, I 

When attributes are disabled, the foreground color for all characters is determined by 
R26(7-4). I 

R27 ADDRESS INCREMENT PER ROW 

An additional feature of the 8563 is the ability to scroll horizontally, both left and right I 

through display 8563 RAM memory. To scroll a window of i horizontal bytes by j 

vertical scan lines across a virtual screen of k horizontal by 1 vertical (i < k) there must 

be (k X 1) bytes of bit-mapped data in display 8563 RAM memory. The 8563 must 

"skip" (k-i) bytes on every scan line, because only i bytes are displayed of a virtual L 

line of k bytes in display 8563 RAM memory. The 8563 has the ability to skip a number 

of bytes, set by writing to R27. If R27 is 0, then no bytes will be skipped. A nonzero 

value in R27 is necessary to allow horizontal smooth-scrolling. _ 

The value in R27 is used to increment the address of the bit-mapped data from one 
scan line to the next and to increment the address of the attributes from one character row 
to the next. Both the bit-mapped data and the attributes will be incremented by the same I 

amount, the value of R27. ^ 

R28(4) 8563 RAM TYPE (44 1 6/4 1 64) 

The data for the displayed text is stored in a dynamic RAM dedicated to the display and '- 

external to the 8563. The CPU accesses this 8563 RAM display memory indirectly 
through the 8563 internal registers. The 8563 internally calculates 16-bit RAM ad- | I 

dresses, so can address up to 64K bytes of 8563 RAM. The 8563 RAM addresses may U 
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be configured to be compatible with 4164 8563 RAMs (64K by 1) or with 4416 8563 
RAMs (16K X 4). Register 28, bit 4 should be initialized to a for operation with 
4416s a 1 for operation with 4164s. 

4416: Row/Col = A7/A15, A6/A13, A5/A12, A4/A11, A3/A10, A2/A9, A1/A8, 
A0/A8 

4164: Row/Col = A7/A15, A6/A14, A5/A13, A4/A12, A3/A11, A2/A10, A1/A9, 
A0/A8 



R28(7-5) CHARACTER SET START ADDRESS 

' The starting location of the character set in display 8563 RAM is determined by 

R28(7-5). These bits form the most significant 3 bits of the 16-bit address used to 
P access character data. If R9(4-0) is greater than 15, then only bits 7-6 of R28 will be 

/ j used, because each character set will occupy 8192 bytes of 8563 RAM memory. 

The character pointers correspond to a displayed character position on the frame. 
The 8-bit pointer selects one of the 256 characters in the character set to be displayed at 
that position on the frame. For a frame of i rows of j characters each, the first j pointers 
will define the characters in the first (top) character row, and (i x j) pointers will need 
to be defined in display 8563 RAM. For 25 character rows of 80 characters each, 2000 
pointers will be needed. 



R29(4-0) UNDERLINE SCAN LINE COUNT 

The number of the scan line used for underline. The underiine is defined as a single scan 
line. Scan line refers to the scan line at the top of the character. 

R32, R33 BLOCK COPY SOURCE ADDRESS 

Block Copy is similar to Block Write, except that the data written to 8563 memory is 
obtained from other successive memory locations. The Block Copy actually 'copies' 
one part of 8563 memory to another. To set this operation up, the CPU writes the initial 
Destination Address to R18/R19, waits for the Update Ready Status bit to be 1 and 
writes a 1, to R24(7) selecting the Block Copy mode. The CPU then writes the initial 
source address to R32 (most significant byte) and R33 (least significant), then the 
number of successive memory locations to be copied should be written to R30. The 
8563 will then read the contents of the first source address and write that data to the first 
destination address. Additional copies will occur at addresses incremented from the 
source and destination addresses, for as many words as are defined in R30. 

R34, R35 DISPLAY ENABLE BEGIN, END 

During the horizontal and vertical synchronization pulses, the R, G, B and I signals must 
be blanked (brought to a low level) to prevent the display of the scanning beam during 
retrace times. Two registers allow the user to adjust the beginning (R34) and end (R35) 
of the horizontal blanking interval. 

Register R34 is programmed with the number of characters from the first dis- 
played character of a row to the first blanked character in that row. Register R35 is 
programmed with the number of characters from the first displayed character of a row to 
the last blanked character in that row. Blanking occurs on all scan lines of a frame. 
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R36(3-0) 8563 RAM REFRESH/SCAN LINE 

The number of Dynamic RAM refresh cycles every scan Hne. These refresh cycles occur 

on displayed and nondisplayed scan lines, during the displayed part of the screen and 

nondisplayed parts (blanked scan lines, vertical borders and vertical sync). Each refresh '- 

address is incremented from the previous refresh address, incrementing through all 

65,536 addresses. The least significant byte of the 16-bit Display 8563 RAM memory I 1 

address is used as the row address to the 8563 RAM. As the 16-bit refresh address is U 

incremented, successive rows of the 8563 RAM are refreshed. 

u 
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INTRODUCTION 



u 



The Commodore 128 has one of the most sophisticated built-in sound synthesizers jj 

available in a personal computer. The synthesizer, called the Sound Interface Device 
(SID), is a chip dedicated solely to generating sound and music. The SID chip is capable , , 

of producing three independent voices (sounds) simultaneously. Each of the voices can j 

be played in one of four types of sounds, called waveforms. The SID chip also has 
programmable Attack, Decay, Sustain and Release (ADSR) parameters. These parame- 
ters defme the quality of a sound. In addition, the synthesizer has a filter you can use to 
choose certain sounds, eliminate others, or modify the characteristics of a sound or sounds. 
All these features add up to a powerful and versatile synthesizer. 

To make it easy for you to select and manipulate the many capabilities of the SID 
chip. Commodore has developed new and powerful BASIC music statements. 

Here are the new sound and music statements available on the Commodore 128: 



u 



SOUND 

ENVELOPE 

VOL 

TEMPO 

PLAY 

HLTER 

The beginning of this section explains these sound statements, in an encyclopedia 
format. The second half describes how to program the SID chip in machine 

language. 

ENVELOPE 

Define a musical instrument envelope 

ENVELOPE n,[,atk] [,dec] [,sus] [rel][,wf] [,pw] 

where: 



u 



n 


Envelope number (0-9) 


atk 


Attack rate (0-15) 


dec 


Decay rate (0-15) 


sus 


Sustain (0-15) 


rel 


Release rate (0-15) 


wf 


Waveform: = triangle 




1 = sawtooth 




2 = variable pulse (square) 




3 = noise 




4 = ring modulation 


pw 


Pulse width (0-4095) 
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u 
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A parameter that is not specified will retain its predefined or currently redefined 
value. Pulse width applies to the width of the variable pulse waveform (wf = 2) only. 
The Commodore 128 has initialized the following ten envelopes: 



I I 



n 





N 


A 


D 


s 


R 


wf 


pw 


instrument 


ENVELOPE 


0, 


0, 


9, 


0, 


0, 


2, 


1536 


piano 


ENVELOPE 


1, 


12, 


0, 


12, 


0, 


1 




accordion 


ENVELOPE 


2, 


0, 


0, 


15, 


0, 







calliope 


ENVELOPE 


3, 


0, 


5, 


5, 


0, 


3 




drum 


ENVELOPE 


4, 


9, 


4, 


4, 


0, 







flute 


ENVELOPE 


5, 


0, 


9, 


2, 


1, 


1 




guitar 


ENVELOPE 


6, 


0, 


9, 


0, 


0, 


2, 


512 


harpsichord 


ENVELOPE 


7, 


0, 


9, 


9, 


0, 


2, 


2048 


organ 


ENVELOPE 


8, 


8, 


9, 


4, 


1, 


2, 


512 


trumpet 


ENVELOPE 


9, 


0, 


9, 


0, 


0, 







xylophone 



FILTER 

Define sound (SID chip) filter parameters 

FILTER [freq], [,Ip] [,bp] [,hp] [,res] 
where: 









i 


freq 


Filter cut-off frequency (0-2047) 




ip 


Low-pass filter on (1), off (0) 


-^ 


bp 


Band-pass filter on (1), off (0) 




hp 


High-pass filter on (1), off (0) 




res 


Resonance (0-15) 



n 

n 



Unspecified parameters result in no change to the current value. 

You can use more than one type of filter at a time. For example, both low-pass 
and high-pass filters can be used together to produce a notch-(or band-reject) filter 
response. For the filter to have an audible effect, at least one type of filter must be 
selected and at least one voice must be routed through the filter. 



338 COMMODORE 128 



EXAMPLES: 



u 



FILTER 1024,0,1,0,2 Set the cutoff frequency at 1024, select the band pass >^ 

filter and a resonance level of 2. J 

FILTER 2000, 1 ,0, 1 , 10 Set the cutoff frequency at 2000, select both the low pass 

and high pass filters (to form a notch reject) and set j i 

the resonance level at 10. |j 



PLAY 








Defines and plays musical notes and elements 


PLAY "Vn,On,Tn,Un,Xn,elements" 


Vn Voice (n = 1-3) 








On Octave (n = 0-6) 








TN Tune Envelope Defaults (n 


= 0-9) 


= piano 








1 = accordion 








2 = calliope 








3 = drum 








4 = flute 








5 = guitar 








6 = harpsichord 








7 = organ 








8 = trumpet 








9 = xylophone 








Un Volume (n = 0-15) 






Xn Filter on (n = 1), 


off (n = 


0) 




Notes: 


A,B,C,D,E,F,G 


Elements: ^ 


# 




Sharp 




$ 




Flat 




W 




Whole note 




H 




Half note 




Q 




Quarter note 




I 




Eighth note 




S 




Sixteenth note 




• 




Dotted 




R 




Rest 




M 




Wait for all voices currently playing to 
end current measure 



u 





u 

J 
U 
Li 
U 



The PLAY statement gives you the power to select voice, octave and tune 
envelope (including ten predefined musical instrument envelopes), the volume and the - 

notes you want to PLAY. All these controls are enclosed in quotes. 

All elements except R and M precede the musical notes in a PLAY string. •- 

y 
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EXAMPLES: 



PLAY "V1O4T0U5X0CDEFGAB" 



PLAY "V305T6U7X1#B$AW.CHDQEIF" 



n 



1 1 

n 



Play the notes C,D,E,F,G,A and 
B in voice 1 , octave 4, tune enve- 
lope (piano), at volume 5, with 
the filter off. 

Play the notes B-sharp, A-flat, 
a whole dotted-C note, a half 
D-note, a quarter E-note and an 
eighth F-note. 



SOUND 

Create sound effects and musical notes 

SOUND v,f,d[,dlr][,m][,s][,w][,p] 

where: 

V voice (1-3) 

f frequency value (0-65535) 

d duration (0-32767) 

dir step direction (0(up), l(down) or 2(oscillate)) default = 

m minimum frequency (if sweep is used) (0-65535) default = 

s step value for sweep (0-32767) default = 

w waveform (0 = triangle, 1 = sawtooth, 2 = variable, 3 = noise) default = 2 

p pulse width (0-4095) default = 2048 

The SOUND command is a fast and easy way to create sound effects and 
musical tones. The three required parameters v,f and d select the voice, frequency 
and duration of the sound. The duration is in units called jiffies. Sixty jiffies equals 
1 second. 

The SOUND command can sweep through a series of frequencies which allows 
sound effects to pass through a range of notes. Specify the direction of the sweep with 
the DIR parameter. Set the minimum frequency of the sweep with M and the step value 
of the sweep with S. Select the appropriate waveform with W and specify P as the width 
of the variable pulse waveform if selected in W. 



n 

n 



EXAMPLES: 



SOUND 1,40960,60 



SOUND 2,20000,50,0,2000,100 



Play a SOUND at frequency 40960 in voice 1 
for 1 second. 

Output a sound by sweeping through frequen- 
cies starting at 2000 and incrementing upward 
in units of 100. Each frequency is played for 
50 jiffies. 
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SOUND 3,5000,90,2,3000,500,1 



This example outputs a range of sounds start- 
ing at a minimum frequency of 3000, tiirough 
5000, in increments of 500. The direction of 
the sweep is back and forth (oscillating). The 
selected waveform is sawtooth and the voice 
selected is 3. 



EXAMPLES: 



Voice 



SOUND I, 49152, 240, 1, 0, 100, 1, 

r 



Frequency . 
Duration _ 



Sweep Direction 

Minimum Sweep Frequency 

Step Value for Sweep 

Waveform 



Pulse Width for Variable Width Waveform 



u 



tj 



10 

20 

30 

40 

50 

60 

70 

80 

90 

100 

110 

120 

130 

140 

150 



DO 

PRINT"VC FREQ DIR 
V=INT(RND(1)*3)+1 
F=INT(RND(1)*65535) 
D=INT(RND{1)*32767) 
DIR=INT(RND(1)*3) 
M=INT(RND(1)*65535) 
S=INT(RND(1)*32767) 
W=INT(RND(1)*4) 
P=INT(RND(1)*4095) 
PRINT V; F;DIR;M;S 



SOUND 
SLEEP 
SOUND 
LOOP 



F, D, 



MIN SV WF 
:REM VOICE 
:REM FREQ 
:REM DURATION 
:REM STEP DIR 
:REM MIN FREQ 
:REM STEP VAL 
:REM WAVEFORM 
:REM PULSE W 
W;P: PRINT: PRINT 
DIR, M, S, W, P 



PW ": PRINT 



u 
u 

u 



0, 0, DIR, 0, 0, W, P 



TEMPO 

Define the speed of the song being played 

TEMPO n 

where n is a relative duration between (0 and 255) 

The actual duration for a whole note is determined by using the formula given 
below: 

whole note duration = 19.22/n seconds 

The default value is 8, and note duration increases with n. 



y 
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! 1 

I 1 



EXAMPLES: 

TEMPO 16 Defines the TEMPO at 16. 
TEMPO 1 Defines the TEMPO at the slowest speed. 
TEMPO 250 Defines the TEMPO at 250. 

VOL 

Define output level of sound 

VOL volume level 

This statement sets the volume for SOUND and PLAY statements. VOLUME 
level can be set from to 15, where 15 is the maximum volume, and is off. VOL 
affects all voices. 



n 

! i 



n 



EXAMPLES: 

VOL Sets volume to its lowest level. 
VOL 15 Sets volume for SOUND and PLAY statements to its highest output. 

CODING A SONG 
FROM SHEET MUSIC 



n 



n 



This section provides a sample piece of sheet music and illustrates how to decode notes 
from a musical staff and translate them into a form the Commodore 128 can understand. 
This exercise is substantially faster and easier if you know how to read music. However, 
you don't have to be a musician to be able to play the tune on your Commodore 128. 
For those of you who cannot read music, Figure 1 1-1 shows how a typical musical staff 
is arranged and how the notes on the staff are related to the keys on a piano. 



Illllllllllilllllllll 



i 
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ijjriiiLiir 



I 



Middle 
C 



Figure il-i. Musical Staff 
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Figure 1 1-2 is an excerpt from a composition titled Invention 13 {Inventio 13 in 
Italian), by Johann Sebastian Bach. Although this composition was written a few 
hundred years ago, it can be played and enjoyed on the most modem of computer 
synthesizers, such as the SID chip in the Commodore 128. Here are the opening 
measures of Invention 13. 



Inventio 13 



/ 




rH^ 


m= 


B 


F= 








Ffl 


^ 


^^ 




— 




i 






^1^ 




m 


-f 




'^ "J' LJ= 




• 1^ 


( 


o-i^K r ft 


"M 


r m 


= 




=f^ 


# 


L^ II 


^ F 


=^f=i 


s — 




— Tn 










3 ' 


tsta 


sa 




B^ 


y-i 




- 
1 


h-^ 1 


LS 


s 




t^ 


Ld — 1 




Figure 1 1-2. Part of Bach's Invention 13 



The best way to start coding a song on your Commodore 128 is to break the notes 
down into an intermediate code. Write down the upper staff notes on a piece of paper. 
Now write down the notes for the lower staff. Precede the note values with a duration 
code. For instance, precede an eighth note with an 8, precede a sixteenth note with a 16, 
and so on. Next, separate the notes so the notes on the upper staff for one measure are 
proportional in time with the notes for one measure on the lower staff. 

If the musical composition had a third staff, you would separate it so the duration 
would be proportional to the two other upper staffs. Once the notes for all the staffs are 
separated into equal durations, a separate and dedicated voice plays each note for a 
particular staff. For example, voice 1 plays the upper staff, voice 2 plays the second 
staff and voice 3 plays the lowest staff. 

Let's say the upper staff begins with a string of four eighth notes. In addition, say 
the lower staff begins with a string of eight sixteenth notes. Since an eighth note is 
proportional in time to two sixteenth notes, separate the notes as shown in Figure 1 1-3. 
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u 

u 
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VI = 8A 8B 8C 8D 

V2 = 16D 16E 16F 16G 16A 16B 16C 16D 

Figure 1 1-3. Synclironizing Notes for Two Voices 
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' ' The synchronization and timing in a musical composition are critical so you must 

make sure the notes in the upper staff for voice 1, for example, are in time agreement 

"^ with the notes in the lower staff for voice 2. The first note in the upper staff in Figure 

I 1 1-3 is an A eighth note. The first two notes for voice 2 are D and E sixteenth notes. In 

this case, you must enter the voice 1 eighth note in the PLAY string first, then follow 

f—, the voice 2 sixteenth notes immediately after it. To continue the example, the second 

1 I note in Figure 11-3 for voice 1 (the upper staff) is a B eighth note. The B eighth note is 

equal in time to the two sixteenth notes, F and G, which appear in the bottom staff for 
voice 2. In order to coordinate the time, enter the B eighth note in the string for voice 1 

I ) and follow it with the two sixteenth notes, F and G, for voice 2. 

! I As a rule, always start with the note with the longer duration. For example, if a 

bar starts with a series of two sixteenth notes on the lower staff for voice 2 and the upper 

f^ staff starts with an eighth note for voice 1 , enter the eighth note in the string first since it 

{ [ must play for the duration while the two sixteenth notes are being fetched by the 

Commodore 128. You must give the computer time to play the longer note first, and 
then PLAY the notes of shorter duration, or else the composition will not be synchronized. 
Here's the program that plays Invention 13. Spaces are omitted in the PLAY string 

' ' to conserve space. For readability in your programs, add space between elements in the 

string. Enter it into your C128 and SAVE it for future use. Now RUN it and sit back 

n and enjoy the music! 

i t 

10 REM INVENTION 13 BACH 

20 TEMPO 6 
p^ 30 PLAY"V104T7U8XO":REM VOICE 1=0RGAN 

; I 40 PLAY"V2O4T0U8X0":REM VOICE 2=PIAN0 

I j 50 REM FIRST MEASURE 

60 A$="V201IAV103IEV202QAV103SA04C03BEV202I#GV103SB04DV104ICV202SAEM" 

70 B$="VlO4IEV2O2SAO3CVlO3l#GV202SBEVlO4IEV2O2SBO3D" 
_, 80 REM SECOND MEASURE 

I; 90 C$="V203ICV103SAEV202IAV103SA04CV2O2I#GVlO3SBEV202IEV103SBO4D" 

i I 100 D?="V104ICV202SAEV103IAV202SA03CV104QRV202SBEB03D" 

' ' 110 REM REM THIRD MEASURE 

120 E$="V203ICV104SREV202IAV104SCEV203ICV103SA04CV202IAV102SEG" 
__ 130 F$="VlO3IFV2O3SDO2AVlO3IAV2O2SFAV104IDV2O2SDFV104IFV201SA02C" 

I I 140 REM FOURTH MEASURE 

I ! 150 G$="V201IBVlO4SFDV2O2IDV103SBO4DV202IGVlO3SGBV2O2IBV103SDF" 

' * 160 HS="V103IEV202SGEVl03IGV202SEGV104ICV202SCEV104IEV201SGB" 

170 REM FIFTH MEASURE 

180 lS="V2OlIAV104SECV2O2ICVlO3SAO4CV103IFV2O2SDFV104IDV201SBO2D" 
P< 190 JS="V201IGV103SDBV201IBV103SGBV103IEV202SCEV104ICV201SA02C" 

I \ 200 REM SIXTH MEASURE 

1 \ 210 K? = "V201IFV1O4SCO3AV2O1IDV1O3SFAV1O3IDV201SGO2GV1O3IBV2O2SFG" 

220 M$="V2OlIAVlO4SCO3AV2O2I#FV104SCEV2OlIBVlO4SD03BV2O2I#GVlO4SDF" 

230 REM SEVENTH MEASURE 
I'm, 240 N$ = "V202ICVlO4SECV202IAVlO4SEGV202IDV104SFEV2O2I$BV104SDC" 

i I 250 0$="V202I#GV103SB04CV202IFV104SDEV202IDV104SFDV201IBV104S#GD" 

) ^ 260 REM EIGHTH MEASURE 

270 P$="V202I#GV104SBDV202IAV104SCAV202IDV104SFDV202IEV103SB04D" 

280 Q$="V202IFV103S#GBV202I#DV104SC03AV202IEV103SEAV202IEV103SB#G" 
,_ 290 REM NINTH MEASURE 

ri 300 RS="V201HAV103SAECE02QA" 

j I 310 PLAY AS: PLAY BS:PLAY CS:PLAY D$:PLAY E$ 

' ' 320 PLAY FS:PLAY G? : PLAY HS:PI.AY I$:PLAY J? 

330 PLAY K$: PLAY MS: PLAY NS:PLAY OS:PLAY PS 

340 PLAY QS:PLAY RS 
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Here are two sample sounds programs that you can try: 

10 REM SOUND LOOPS 

20 REM CHANGES STEP VALUE, DIRECTION AND WAVEFORM 

30 SV=1000:REM STEP VALUE 

40 DO 

50 PRINT:PRINT "SV=" ;SV: PRINT 

60 : DIR=0 :REM SWEEP DIRECTION 

70 : DO 

80 : WF=0:REM WAVEFORM 

90 : DO 

100 : SOUND 1, 40000, 120, DIR, 2000, SV.WF 

110 : PRINT "WF=";WF;:WF=WF+1 

120 ! LOOP UNTIL WF=4 

130 : PRINT "DIR=" ;DIR!DIR=DIR+1 

140 : LOOP UNTIL DIR = 3 

150 SV=SV+2000 

160 LOOP UNTIL SV > 20000 



u 






10 REM C128-MODE JOYSTICK MUSICIAN 

20 REM PLAYS NOTES C THROUGH A IN EACH OCTAVE 

30 REM TO INCREASE THE NOTE VALUE, PUSH JOYSTICK FORWARD 

40 REM TO DECREASE NOTE VALUE, PULL BACK 

50 REM TO INCREASE OCTAVE VALUE, PUSH JOYSTICK TO THE RIGHT 

60 REM TO DECREASE OCTAVE VALUE, PUSH JOYSTICK TO THE LEFT 

A$(5)="G'":A$(6) = "A":AS(7) = "B" 



70 A$(1)="C":AS(2)="D":A$(3)="E":AS(4)="F 

80 Z=4:REM INITIALIZE TO FOURTH OCTAVE 

90 SCNCLR :REM CLEAR SCREEN 

100 INPUT"ENTER VOICE 1 INSTRUMENT NUMBER (0-9)";N$ 

110 INPUT"ENTER VOICE 2 INSTRUMENT NUMBER (0-9)", -OS 

120 INPUT"ENTER VOICE 3 INSTRUMENT NUMBER (0-9)", -PS 

130 PRINT: PRINT: PRINT: PRINT: PRINT: PRINT" INCREASE NOTE" 

140 PRINT: PRINT" *":PRINT 

150 PRINT"DECREASE OCTAVE < — — > INCREASE OCTAVE" 

160 PRINT: PRINT" V": PRINT 

170 PRINT:PRINT" DECREASE NOTE":PRINT 

180 PRINT: PRINT"TO INCREASE OR DECREASE NOTE OR OCTAVE"; 

190 PRINT: PRINT"WITHO0T PLAYING NOTES, HOLD DOWN THE " ; 

200 PRINT"FIRE BUTTON WHILE POSITIONING THE" ; 

210 PRINT: PRINT" JOYSTICK IN THE APPROPRIATE DIRECTION"; 

220 QS="V1"+"T"+NS:REM VOICE 1 INSTRUMENT 

230 R$="V2"+"T"+0S:REM VOICE 2 INSTRUMENT 

240 S$="V3"+"T"+PS:REM VOICE 3 INSTRUMENT 

250 DO 



260 
270 
280 
290 
300 
310 
320 
330 
340 
350 
360 
370 
380 
390 
400 
410 
420 
430 
440 
450 



DO 



A=J0Y(1):REM GET JOY VALUE 

IF A=0 THEN LOOP:REM IF ZERO LOOP AND GET ANOTHER 
B=A :REM STORE THE VALUE FOR LATER CHECKING 
Z$="0"+STR$(Z) :REM UPDATE OCTAVE 

TS=Z$+QS+AS(I) :REM CONSTRUCT VOICE 1 PLAY STRING 
US=Z$+RS+A$(I) :REM CONSTRUCT VOICE 2 PLAY STRING 
V$=ZS+S$+A$(I) :REM CONSTRUCT VOICE 3 PLAY STRING 



IF (A AND 128)=128 THEN 400 
PLAY T$:REM PLAY VOICE 1 
PLAY U$:REM PLAY VOICE 2 
PLAY V?:REM PLAY VOICE 3 

IF (A=l OR A=129) AND (I<8) THEN 
IF (A=5 OR A=133) AND (I>0) THEN 






u 

u 
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1=1+1: REM INCREMENT NOTE VALUE 
1=1-1 :REM DECREMENT NOTE VALUE 



IF (A=3 OR A=131) AND (Z<6) THEN Z=Z+1:REM INCREMENT OCTAVE 
IF (A=7 OR A=135) AND (Z>0) THEN Z=Z-1:REM DECREMENT OCTAVE 
A=J0Y(1):REM GET NEXT JOY VALUE 
LOOP WHILE A=B 



460 LOOP:REM DO IT AGAIN 
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SOUND AND MUSIC 
IN CI 28 MODE 
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I i 
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BACKGROUND: 

THE CHARACTERISTICS OF SOUND 

Every sound you hear is actually a sound wave traveling through the air. Like any wave, 
a sound (sine) wave can be represented graphically and mathematically (see Figure 1 1-4). 




Figure 1 1-4. Sine Wave 

The sound wave moves (oscillates) at a particular rate (frequency) which deter- 
mines the overall pitch (the highness or lowness of the sound). 

The sound is also made up of harmonics, which are accompanying multiples of the 
overall frequency of the sound or note. The combination of these harmonic sound waves 
give the note its qualities, called timbre. Figures 11-5 shows the relationship of basic 
sound frequencies and harmonics. 
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-RESULTANT WAVE 

-FUNDAMENTAL (1ST HARMONIC) 




2N0 HARMONIC 3RD HARMONIC 

Figure 1 1-5. Frequency and (Harmonics 



The timbre of a musical tone (i.e., the way a tone sounds) is determined by the 
tone's waveform. The Commodore 128 can generate four types of waveforms: triangle, 
sawtooth, variable pulse and noise. See Figure 1 1-6 for a graphic representation of these 
four waveforms. 
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Figure 1 1-6. Sound Waveform Types 
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The volume of a sound changes throughout the duration of the note, from when 

you first hear it until it is no longer audible. These volume quahties are referred to as 

p Attack, Decay, Sustain and Release (ADSR). Attack is the rate at which a musical note 

j I reaches its peak volume. Decay is the rate at which a musical note decreases from its 

peak volume to its midranged (sustain) level. Sustain is the level at which a musical note 

,_^ is played at its midrange volume. Release is the rate at which a musical note decreases 

I j from its sustain level to zero volume. The ENVELOPE generator controls the ADSR 

parameters of sound. See Figure 1 1-7 for a graphical representation of ADSR. The 

Commodore 128 can change each ADSR parameter to sixteen different levels. This 

P gives you absolute flexibility over the ENVELOPE generator and the resulting proper- 

i i ties of the volume of the sound. 
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j i Figure 1 1-7. ADSR Phases 



One of the most powerful Commodore 128 sound statements — ^the one that 
controls the ADSR and waveform— is the ENVELOPE statement. The ENVELOPE 
statement sets the different controls in the synthesizer which make each sound unique. 
The ENVELOPE gives you the power to manipulate the SID synthesizer. 



Here are the definitions of the parameters within the Envelope statement: 

Envelope The properties of a musical note specified by the waveform and the attack, 
decay, sustain and release settings of the note. For example, the envelope for a 
guitar note has a different ADSR and waveform than that for a flute. 

Waveform The type of sound wave created by the combination of accompanying 
musical harmonics of a tone. The accompanying harmonic sound waves are 
multiples of, and are based on the overall frequency of the tone. The qualities of 
the tone generated by each waveform are recognizably different from one another 
and are represented graphically in Figure 1 1-6. 

Pulse Width The length of time between notes, generated by the pulse waveform. 

The Commodore 128 has ten predefined envelopes for ten different musical 
instruments. In using the predefined envelopes you do not have to specify the ADSR 
parameters, waveform and pulse width settings — this is already done for you. All you 
have to do is specify the envelope number. The rest of the parameters are chosen 
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ENVELOPE 

NUMBER INSTRUMENT ATTACK DECAY SUSTAIN RELEASE WAVEFORM WIDTH 

Piano 9 2 1536 

1 

2 

3 

4 

5 

6 

7 

8 

9 Xylophone 9 

Figure 1 1-8. Default Parameters for ENVELOPE Statement 
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Accordion 


12 
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15 





Drum 
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Flute 
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Guitar 
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Organ 
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Trumpet 
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2048 
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automatically by the Commodore 128. Here are the preselected envelopes for different U 

types of musical instruments: 
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Once you have selected the ENVELOPE, ADSR, VOLume and TEMPO, use the 

FILTER to perfect your synthesized sounds. In your program, the FILTER statement i i 

will precede the PLAY statement. First you should become comfortable with generating || 

the sound and worry about FILTERing last. Since the SID chip has only one filter, it 

applies to all three voices. Your computerized tunes will play without FILTERing, but 

to take full advantage of the music synthesizer, use the FILTER statement to increase j | 

the sharpness and quality of the sound. '—' 

In the first paragraph of this section. The Characteristics of Sound, we defined a 
sound as a wave traveling (oscillating) through the air at a particular rate. The rate at j ( 

which a sound wave oscillates is called the wave's frequency. Recall that a sound wave [J 

is made up of an overall frequency and accompanying harmonics, which are multiples of 
the overall frequency. See Figure 1 1-5. The accompanying harmonics give the sound its 
timbre, the qualities of the sound which are determined by the waveform. The filter i, 

within the SID chip gives you the ability to accent and eliminate the harmonics of a 
waveform and change its timbre. 

The SID chip filters sounds in three ways: low-pass, band-pass and high-pass j ' 

filtering. These filtering methods are additive, meaning you can use more than one filter 
at a time. Low-pass filters out frequencies above a certain level you specify, called the 
cutoff frequency. The cutoff frequency is the dividing line that marks the boundary of 
which frequency level will be played and which will not. In low-pass filtering, the SID 
chip plays all frequencies below the cutoff frequency and filters out the frequencies 
above it. As the name implies, the low frequencies are allowed to pass through the 
filter and the high ones are not. The low-pass filter produces full, solid sounds. 
See Figure 1 1-9. 
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Figure 1 1-9. Low-pass Filter 
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Conversely, the high-pass filter allows all the frequencies above the cutoff fre- 
quency to pass through the chip. All the ones below it are filtered out. See Figure 1 1-10. 
The high-pass filter produces tinny, hollow sounds. 
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Figure I l-IO. High-pass Filter 
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The band-pass filter allows a range of firequencies partially above and below the 
cutoff frequency to pass through the SID chip. All other frequencies above and below 
the band surrounding the cutoff frequency are filtered out. See Figure 11-11. 
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Figure 11-11. Band-pass Filter 

ADVANCED FILTERING 

Each of the previous FILTERing examples used only one type of filtering at a time. You 
can combine the SID chip's three methods of filtering with each other to achieve 
different filtering effects. For example, you can enable the low-pass and high-pass filters 
at the same time to form a notch reject filter. A notch reject filter allows the frequencies 
below and above the cutoff to pass through the SID chip, while the frequencies close to 
the cutoff frequency are filtered out. See Figure 1 1-12 for a graphic representation of a 
notch reject filter. 
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Figure 11-12. Notcli Reject Filter 
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You can also add either the low-pass or high-pass filter to the band-pass filter to 
obtain interesting effects. By mixing the band-pass filter with the low-pass filter, you 
can select the band of frequencies beneath the cutoff frequency and below. The rest are 
filtered out. 

By mixing the band-pass and the high-pass filters, you can select the band of 
frequencies above the cutoff frequency and higher. All the frequencies below the cutoff 
are filtered out. 
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Experiment with the different combinations of filters to see all the different types 
of accents you can place on your musical notes and sound effects. The filters are 
designed to perfect the sounds created by the other components of the SID chip. Once 
you have created the musical notes or sound effects with the SID chip, go back and add 
the FILTERing to your programs to make them as crisp and clean as possible. 

Now you have all the information you need to write your own musical programs in 
Commodore 128 BASIC. Experiment with the different waveforms, ADSR settings, 
TEMPOS and FILTERing. Look in a book of sheet music and enter the notes from a 
musical scale in sequence within a play string. Accent the notes in the string with the 
SID control characters. You can combine your Commodore 128 music synthesizer with 
CI28 mode graphics to make your own videos or "movies" complete with sound 
tracks. 



AUDIO INPUT TO THE SID CHIP 
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The SID chip has a little known additional feature that most computers do not offer: 
audio input. This allows you to channel your own music, such as an electric guitar, your 
voice through a microphone or any other (high impedence, line level) instrument — ^you 
can actually "jam" with the CI 28. 

In order to connect properly to the computer, you must devise your own cable or 
buy one with the correct connections. Get a cable with an 8-pin DIN connector on the 
end you are plugging into the CI 28. Connect pins 2 (ground), 3 (audio out), and 5 (audio 
in) on the 8-pin end. 

Here's the pinout: 

Video Connector — ^This DIN connector supplies direct audio and composite video 
signals. These can be connected to the Commodore monitor or used with separate 
components. This is the 40-column output connector. 
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PIN 


TYPE 


NOTE 


1 


LUM/SYNC 


Luminance/SYNC output 


2 


GND 




3 


AUDIO OUT 




4 


VIDEO OUT 


Composite signal output 


5 


AUDIO IN 




6 


COLOR OUT 


Chroma signal output 


7 


NC 


No connection 


8 


NC 


No connection 



Run the three connecting wires inside the cable to attach to the audio in, audio out 
and ground on the end of your component. 

You can connect the CI 28 to your stereo system or VCR and channel sound 
through your speakers. Be careful, however, not to exceed the standard electrical 
restrictions. See the SID chip specs in Chapter 16 under the description EXT IN 
(Pin 26). 

Using the CI 28 in these ways opens your eyes to how flexible a personal computer 
can be and how it can communicate with a wide range of devices in your home, 
including your telephone (with an additional modem), VCR, stereo, TV — and don't 
forget the electric guitar! 

PROGRAMMING THE SID CHIP 
IN MACHINE LANGUAGE 

This section provides an algorithm and the coded program procedure to play music on 
the C128. 

First you need to know the key SID locations in the C128 memory map. Here's an 
abbreviated SID memory map, which is exactly the same in both C128 and C64 modes. 
Register is located at address 54272 ($D400). 
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Here's the general algorithm to output sound from the SID chip in voice 1. 



The durations of the standard musical notes are as follows: 



NOTE TYPE 


DURATION 


'/l« 


128 


'/» 


256 


DOTTED >/8 


384 


•/4 


512 


y* + '/i« 


640 


DOTTED '/4 


768 


'A 


1024 


Vl + Vl6 


1152 


Vi + '/« 


1280 


DOTTED Vi 


1536 


WHOLE 


2048 



u 



1. Clear the sound chip (For $D400-$D41C) \ \ 

2. Select ATTACK and DECAY for each voice ($D405)vl M 

3. Select SUSTAIN and release for each voice ($D406) vl 

4. Select a waveform ($D404 for vl) 

5. Set the volume ($D418) | j 

6. Set the frequency of the note with a low byte ($D400) and high byte "-^ 
($D401) fxom the Musical Note Table in Figure 1 1-15 at the end of this chapter. 

If you want to output a certain frequency level, use this equation: j I 

F„ = F out/.06097 ^ 

Round off the (Fn) frequency witii the integer function and divide the result into the , 

low byte and high byte. | \ 

In decimal: ^ 

Fhi = Fn/256 is the high byte 
and: 

Flow = F„ -(256 * Fhi) is the low byte 

To get a feel for the ranges of notes, experiment with the SOUND command in ! * 

BASIC. U 

7. Place the high byte in Frequency Control Register (in $D401) for the 
appropriate voice. \ 

8. Place the low byte in the (low byte) frequency control register for the ^ 
appropriate voice ($D400). 

9. Initiate (GATE) the note or tone. Gating means to start the ATTACK, \ j 
DECAY and SUSTAIN cycle of the tone. Set bit of $D404 (VI), $D40B(V2) [J 
and $D412(V3), respectively. 

10. Leave bit set for the duration you wish to play the note or tone. 

11. Clear the GATE bit. 1 J 
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' ' To synchronize three voices, divide each measure into sixteen equal parts. Play 

(Gate) the notes with longer duration first, then gate the values of smaller duration, but 

n of equal proportion, next. For example, one staff has an eighth note. The staff below it 

i I has two sixteenth notes. Play the note of longer duration so they can be gated while the 

other faster notes are being fetched. 
n The following machine language program plays musical notes in one voice. The 

■' j musical note data begins at location $1890. The data for each note is stored in the four 

byte format starting at $1890 as follows: 

( i Frequency (low byte/high byte) 

' ' Duration (low byte/high byte) 

r-| For example, the data for the second note starts at location $1894, data for the 

I { third note begins at location $1898 and so on. 

For now, sample data has been supplied. Eventually, place your own data beginning 
—, at location $1890. See Figure 1 1-15 at the end of this chapter for the low- and high-byte 

n frequency values to place in the SID frequency control registers. Refer to the duration 

' ' table on page 354 for the byte values for the note duration. 

The NOP instructions are added between instruction sequences for readability. 
n Here's the program listing as it appears in the Machine Language Monitor: 






1 1 



\\ 



f ! 



READY. 



Mo^aTOR 














PC SR AC XR YR SP 






; FBOOO ( 


30 00 00 00 F8 






. 01800 


A2 


00 




LDX 


#$00 




. 01802 


8A 






TXA 






. 01803 


9D 


00 


D4 


STA 


$D400, 


X 


. 01806 


E8 






INK 






. 01807 


EO 


19 




CPX 


#$19 




. 01809 


DO 


F8 




BNE 


$1803 




. 0180B 


EA 






NOP 






. 0180C 


EA 






NOP 






. 0180D 


EA 






NOP 






. 0180E 


A2 


05 




LDX 


#$05 




. 01810 


A9 


F5 




LDA 


#$F5 




. 01812 


9D 


00 


D4 


STA 


$D400, 


,X 


. 01815 


EA 






NOP 






. 01816 


EA 






NOP 






. 01817 


EA 






NOP 






. 01818 


A2 


06 




LDX 


#$06 




. 0181A 


A9 


A3 




LDA. 


#$A3 




. 0181C 


9D 


00 


D4 


STA 


$D400, 


,x 


. 0181F 


EA 






NOP 






. 01820 


EA 






NOP 






. 01821 


EA 






NOP 






. 01822 


EA 






NOP 






. 01823 


A2 


18 




LDX 


#$18 




. 01825 


A9 


OF 




LDA 


#$0F 




. 01827 


9D 


00 


D4 


STA 


$D400. 


,x 


. 0182A 


EA 






NOP 






. 0182B 


EA 






NOP 






. 0182C 


EA 






NOP 






. 0182D 


AO 


00 




LDY 


#$00 




. 0182F 


A2 


00 




LDX 


#$00 




. 01831 


B9 


90 


18 


LDA 


$1890, 


,Y 
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. 01834 


FO 


3F 




BEQ 


51875 


. 01836 


9D 


00 


D4 


STA 


$D400,X 


. 01839 


E8 






I NX 




. 0183A 


C8 






I NY 




. 0183B 


B9 


90 


18 


LDA 


S1890,Y 


. 0183E 


9D 


00 


D4 


STA 


$D400,X 


. 01841 


EA 






NOP 




. 01842 


EA 






NOP 




. 01843 


EA 






NOP 




. 01844 


C8 






I NY 




. 01845 


B9 


90 


18 


LDA 


$1890, Y 


. 01848 


85 


FA 




STA 


SFA 


. 0184A 


C8 






I NY 




. 0184B 


B9 


90 


18 


LDA 


S1890,Y 


. 0184E 


85 


FB 




STA 


SFB 


. 01850 


A2 


04 




LDX 


#S04 


. 01852 


A9 


21 




LDA 


#S21 


. 01854 


9D 


00 


D4 


STA 


$D400,X 


. 01857 


EA 






NOP 




. 01858 


EA 






NOP 




. 01859 


EA 






NOP 




. 0185A 


EA 






NOP 




. 0185B 


C6 


FA 




DEC 


$FA 


. 0185D 


DO 


FC 




BNE 


S185B 


. 0185F 


C6 


FB 




DEC 


SFB 


. 01861 


DO 


F8 




BNE 


$185B 


. 01863 


EA 






NOP 




. 01864 


A2 


04 




LDX 


#$04 


. 01866 


A9 


20 




LDA 


#$20 


. 01868 


9D 


00 


D4 


STA 


$D400,X 


. 0186B 


EA 






NOP 




. 0186C 


EA 






NOP 




. 0186D 


EA 






NOP 




. 0186E 


C8 






I NY 




. 0186F 


4C 


2F 


18 


JMP 


$182F 


. 01872 


EA 






NOP 




. 01873 


EA 






NOP 




. 01874 


EA 






NOP 




. 01875 


A2 


18 




LDX 


#$18 


. 01877 


A9 


00 




LDA 


#$00 


. 01879 


9D 


00 


D4 


STA 


$D400,X 


. 0187C 


00 






BRK 





Enter the program in memory with the Machine Language Monitor and save it. 
Run the program with the following command: 

GF1800 



ii 
u 

l! 



1 ; 

U 



U 



U 



>01890 IE 19 80 00 IC 41 80 00 

>01898 IE 19 80 00 IC 41 80 00 

>018A0 IE 19 80 00 IC 41 00 00 

>018A8 IE 19 80 00 IC 41 80 00 

>018B0 IE 19 80 00 IE 19 80 00 

>018B8 IE 19 80 01 IE 19 80 01 

>018C0 IE 19 80 04 IC 19 80 04 \ 

>018C8 IE 19 80 04 IC 41 80 00 ^ 

>018D0 IE 19 80 00 IC 41 00 00 . ^ 

>018D8 21 21 00 00 00 00 00 00 

>018E0 OD 54 08 DO D7 AD 7B 08 

>018E8 8D 6C 08 AD 7C 08 8D 6D \ / 



LJ 
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The program plays a series of notes in a single voice (voice 1). Here's a line by 
line description of the instructions in the program. 

The instructions stored in locations $1800 through $180A clear the SID registers 
($D400-$D418) to zero. This is a recommended programming practice, so you can 
assume that all the SID registers are initialized to zero. 

The instructions stored in locations $180E through $1814 assign the attack/decay 
values in the SID envelope generator. In this program, attack is set at (15:$0F) and the 
decay is set at 5. This attack setting makes the sounds seem as if they are far away and 
traveling closer, similar to the way a train sounds as it approaches from far away. 

I i The instructions stored in locations $1818 through $18 IE select the sustain/release 

values for the voice 1 envelope generator. In this case the sustain duration is set on 10 
($0A) and the release rate is set to 3. For more information on the ADSR settings, see 

n the beginning of the chapter. 

i I The next sequence of instructions ($1823-$ 1829) sets the volume to maximum 

output (15:$0F). Notice that the last three instruction sequences loaded the X register 

p with the register number, loaded the accumulator with the appropriate value and stored 

' the value in the location of the start of the SID plus an offset in the X register. This 

programming style is easy to follow and is standardized throughout the program. 

The instructions stored in locations $182D through $I83E get the low- and 
high-byte frequency values for the musical note data, and place them into the low- and 
high-byte frequency control registers for voice 1 . First the X and Y registers are cleared 
to zero. The Y register is used as an index to the musical note data in memory starting at 

n location $1890. To access successive bytes for frequency and duration, the Y index 

register is incremented. The X register is used as an index to access the low- and 
high-byte frequency control registers at locations $D400 and $D40I. In this program 
segment, the X register can only have one of two values; to access location $D400 and 
1 to access location $D401. 

The first time through the loop, the instruction starting at location $1831 (LDA 
$1890,Y) loads the musical data value (low byte frequency) into the accumulator. The 
next instruction (BEQ $1875) checks to see if this value is equal to zero. If it is, control 
passes to location $1875, the volume is cleared to zero, and the program ends. This 
suggests that to end the program, place a zero in the low byte data element. This 
mechanism acts as a data terminator, since no additional data is read if the low-byte 
value of a musical note equals zero. If the data value does not equal zero, it is stored in 
the low byte frequency control register for voice I . 

Both the X and Y registers are incremented, and the next musical data value, this 
time at $1891, is loaded into the accumulator with the instruction beginning at location 
$183B. The next instruction (STA $D400,X) stores the data value in the high-byte 
frequency control register ($D401) for voice 1. 

The instruction at location $1844 increments the Y register. The next load 
instruction starting at location $1845 loads the accumulator with the next data element in 
memory, this time the low byte for the duration of the note. The duration note table is 
found on page 252. The low-byte duration is stored in zero page location $FA. The Y 
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register is incremented again and the high byte duration is loaded into the accumulator '— * 

and stored in zero page location $FB. These two locations are decremented in the 
instructions stored in location $185B through $1862. | | 

The instructions stored in locations $1850 through $1857 GATE the note, in other |j 

words play the note. To output audible notes, each voice has a gate bit which initiates the 
sound from the envelope generator for a particular voice. Bit of location $D404 is the 
gate bit for voice 1. To gate a bit, set bit and also set the bit for the desired wave- j 

form at the same time. In this case, the sawtooth waveform is gated on (32+1 = $21). ^ 

At this point, the sawtooth waveform is gated on and is playing in the voice 1 
envelope generator. The selected frequency is output until you turn off the gate bit. * I 

Here's where the duration of the note comes into play. The instructions stored in N 

locations $185B through $1862 decrement the low and high byte duration value stored 
in zero page locations $FA and $FB respectively. These instructions act as a time delay 
which count through the loops using the duration values from page 354 that are stored in I { 

the musical data region starting at $1890 in memory. When both $FA and $FB are equal i— i 

to zero, program control drops through to the instructions stored at $1864 through 
$186A. These instructions clear the voice 1 gate bit and stop the envelope generator i 

from outputting sound. ) 

At this point, the Y register is incremented ($186E) and the program jumps to 
$182F where the X register is cleared to zero. Since the Y register was already ~ 

incremented before the JMP instruction in location $186F-71, the low byte frequency } j 

value for the second note is already pointed to by the Y register plus the base address of U 

$1890. The program then loads that low-byte value and stores it in the location $D400 
plus the offset of the X register, in this case 0. That gives the appropriate address $D400 \ 

for the voice 1 (low byte) frequency control register. These instructions are executed \ 

repetitively until a low-byte frequency of zero is encountered. When the low-byte 
frequency equals zero, control is passed to location $1875, the volume is cleared to 
zero, and the program breaks. 

This program plays 19 notes, and on the 20th a zero is detected as the low-byte 
frequency value (in location $18DC), so volume is set to zero and the program ends. 
This data is entered as an example. Place your data there instead according to the note 
table in Figure 11-15 at the end of the chapter and the duration table on page 354. I i 

Expand on this example. Add multiple voices using different waveforms. Utilize 
the filter to perfect the quality of the musical notes. Use this program as a basis for your 
own full-featured musical program. \ | 

u 



The 6581 SID chip lets you create more complex harmonic structures through synchro- 
nization or ring modulation of two voices. 

The process of synchronization is basically a logical ANDing of two wave forms. 
When either is zero, the output is zero. 

Here's a synchronization algorithm: 
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1 Clear sound chip registers. 

2 Set high frequency voice 1. 

3 Set Attaclc/Decay for voice 1(A = 13, D = 11). 

4 Set high frequency voice 3. 

5 Set volume 15. 

6 Set start triangle, sync waveform control for voice 1. 

7 Timing loop. 

8 Clear triangle, sync waveform control for voice 1. 

9 Wait, then turn off volume. 



The synchronization feature is enabled (turned on) in step 6, where bits 0,1, and 4 
|~| of register $D404 are set. Bit 1 enables the syncing function between voice 1 and voice 

I I 3. Bits and 4 have their usual functions of gating voice 1 and setting the triangular 

waveform. 

Ring modulation (accomplished for voice I by setting bit 2 of register $D404 in 
step 6 of the algorithm) replaces the triangular output of oscillator 1 with a "ring 
modulated" combination of oscillators 1 and 3. This produces non-harmonic overtone 
structures for use in mimicking bell or gong sounds. 



SID REGISTER DESCRIPTION 

(— , Following is a register-by-register description of the SID chip in numerical order. 

I j 

VOICE I 



FREQ LO/FREQ HI (Registers 00,01) 

Together these registers form a 16-bit number which linearly controls the frequency of 
Oscillator 1 . The frequency is determined by the following equation: 

Fout = (Fn X Fc,k/16777216) Hz 

Where Fn is the 16-bit number in the Frequency registers and Fdk is the system clock 
applied to the 02 input (pin 6). For a standard 1.0-MHz clock, the frequency is given 
by: 

Fout = (Fn X 0.06097) Hz 

n A complete table of values for generating eight octaves of the equally tempered 

[ I musical scale with concert A (440 Hz) tuning is provided in Figure 11-15. It should be 

noted that the frequency resolution of SID is sufficient for any tuning scale and allows 
|— ^ sweeping from note to note (portamento) with no discemable frequency steps. 

' PW LO/PW HI (Registers 02,03) 

Together these registers form a 12-bit number (bits 4-7 of FW HI are not used) which 
linearly controls the Pulse Width (duty cycle) of the Pulse waveform on Oscillator 1 . 
The pulse width is determined by the following equation: 
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PWou, = (PW„/40.95) % U 

Where PW„ is the 12-bit number in the Pulse Width registers. 

The pulse width resolution allows the width to be smoothly swept with no discern- I 

able stepping. Note that the Pulse waveform on Oscillator 1 must be selected in order ^ 

for the Pulse Width registers to have any audible effect. A value of or 4095 ($FFF) in 
the Pulse Width registers will produce a constant DC output, while a value of 2048 \ | 

($800) will produce a square wave. 



<^ 



U 



U 



CONTROL REGISTER (Register 04) 

This register contains eight control bits which select various options on Oscillator 1 . I 

GATE (Bit 0): The GATE bit controls the Envelope Generator for Voice 1. When this 
bit is set to a one, the Envelope Generator is Gated (triggered) and the ATTACK/ 
DECAY/SUSTAIN cycle is initiated. When the bit is reset to a zero, the RE- L 

LEASE cycle begins. The Envelope Generator controls the amplitude of Oscillator 
1 appearing at the audio output, therefore, the GATE bit must be set (along with j 

suitable envelope parameters) for the selected output of Oscillator 1 to be audible. I 

A detailed discussion of the Envelope Generator can be found in this book in the 
chapter on Hardware Overview. — 

SYNC (Bit I): The SYNC bit, when set to a one, synchronizes the fundamental 
frequency of Oscillator 1 with the fundamental frequency of Oscillator 3, produc- 
ing "Hard Sync" effects. 

Varying the frequency of Oscillator 1 with respect to Oscillator 3 produces a 
wide range of complex harmonic structures from Voice 1 at the frequency of 
Oscillator 3. In order for sync to occur. Oscillator 3 must be set to some 
frequency other than zero but preferably lower than the frequency of Oscillator 1. , , 

No other parameters of Voice 3 have any effect on sync. I 

RING MOD (Bit 2): The RING MOD bit, when set to a one, replaces the Triangle 
waveform output of Oscillator 1 with a "Ring Modulated" combination of 
Oscillators 1 and 3. Varying the frequency of Oscillator 1 with respect to J 

Oscillator 3 produces a wide range of non-harmonic overtone structures for L-! 

creating bell or gong sounds and for special effects. In order for ring modulation 
to be audible, the Triangle waveform of Oscillator 1 must be selected and ' 

Oscillator 3 must be set to some frequency other than zero. No other parameters of I 

Voice 3 have any effect on ring modulation. 

TEST (Bit 3): The TEST bit, when set to a one, resets and locks Oscillator 1 at zero until 
the TEST bit is cleared. The Noise waveform output of Oscillator 1 is also reset and 
the Pulse waveform output is held at a DC level. Normally this bit is used for testing 
purposes, however, it can be used to synchronize Oscillator 1 to extemal events, allow- 
ing the generation of highly complex waveforms under real-time software control. 

(Bit 4): When set to a one, the Triangle waveform output of Oscillator 1 is selected. 
The Triangle waveform is low in harmonics and has a mellow, flute-like quality. 

(Bit 5): When set to a one, the Sawtooth waveform output of Oscillator 1 is selected. 
The Sawtooth waveform is rich in even and odd harmonics and has a bright, 
brassy quality. 
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(Bit 6): When set to a one, the Pulse waveform output of Oscillator 1 is selected. The 
harmonic content of this waveform can be adjusted by the Pulse Width registers, 
producing tone qualities ranging from a bright, hollow square wave to a nasal, 
reedy pulse. Sweeping the pulse width in real-time produces a dynamic "phas- 
ing" effect which adds a sense of motion to the sound. Rapidly jumping between 

(— j different pulse widths can produce interesting harmonic sequences. 

I I NOISE (Bit 7): When set to a one, the Noise output waveform of Oscillator 1 is 

selected. This output is a random signal which changes at the frequency of 
Oscillator 1. The sound quality can be varied from a low rumbling to hissing 

[j white noise via the Oscillator 1 Frequency registers. Noise is useful in creating 

' -' explosions, gunshots, jet engines, wind, surf and other unpitched sounds, as well 

as snare drums and cymbals. Sweeping the oscillator frequency with Noise 

|~| selected produces a dramatic rushing effect. 

I I One of the output waveforms must be selected for Oscillator 1 to be audible, 

however, it is NOT necessary to de-select waveforms to silence the output of 
Voice 1 . The amplitude of Voice 1 at the final output is a function of the Envelope 
Generator only. 



n 
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NOTE: The oscillator output waveforms are NOT additive. If more than 
one output waveform is selected simultaneously, the result will be a 
logical ANDing of the waveforms. Although this technique can be used 
to generate additional waveforms beyond the four listed above, it must be 
used with care. If any other waveform is selected while Noise is on, the 
Noise output can "lock up." If this occurs, the Noise output will remain 
silent until reset by the TEST bit or by bringing RES (pin 5) low. 



ATTACK/DECAY (Register 05) 

Bits 4-7 of this register (ATK0-ATK3) select 1 of 16 ATTACK rates for the Voice 1 
Envelope Generator. The ATTACK rate determines how rapidly the output of Voice 1 
rises from zero to peak amplitude when the Envelope Generator is gated. The 16 
ATTACK rates are listed in Figure 1 1-14. 

Bits 0-3 (DCY0-DCY3) select 1 of 16 DECAY rates for the Envelope Generator. 
The DECAY cycle follows the ATTACK cycle and the DECAY rate determines how 
rapidly the output falls from the peak amplitude to the selected SUSTAIN level. The 16 
DECAY rates are listed in Figure 1 1-14. 

SUSTAIN/RELEASE (Register 06) 

Bits 4-7 of this register (STN0-STN3) select 1 of 16 SUSTAIN levels for the Envelope 
Generator. The SUSTAIN cycle follows the DECAY cycle and the output of Voice 1 
will remain at the selected SUSTAIN amplitude as long as the gate bit remains set. The 
SUSTAIN levels range from zero to peak amplitude in sixteen linear steps, with a 
SUSTAIN value of selecting zero amplitude and a SUSTAIN value of 15 ($F) 
selecting the peak amplitude. A SUSTAIN value of 8 would cause Voice 1 to SUSTAIN 
at an amplitude one-half the peak amplitude reached by the ATTACK cycle. 
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Bits 0-3 (RLS0-RLS3) select 1 of 16 RELEASE rates for the Envelope Genera- 
tor. The RELEASE cycle follows the SUSTAIN cycle when the Gate bit is reset to zero. 
At this time, the output of Voice 1 will fall from the SUSTAIN amplitude to zero 
amplitude at the selected RELEASE rate. The 16 RELEASE rates are identical to the 
DECAY rates as listed in Figure 1 1-14. 



u 



NOTE: The cycling of the Envelope Generator can be altered at any 
point via the Gate bit. The Envelope Generator can be gated and re- 
leased without restriction. For example, if the gate bit is reset before the 
envelope has finished the ATTACK cycle, the RELEASE cycle will 
immediately begin, starting from whatever amplitude had been reached. 
If the envelope is then gated again (before the RELEASE cycle has 
reached zero amplitude), another ATTACK cycle will begin, starting 
from whatever amplitude had been reached. This technique can be used 
to generate complex amplitude envelopes via real-time software control. 



VALUE 



ATTACK RATE 



DECAY/RELEASE RATE 



DEC (HEX) 



(TIME/CYCLE) 



TIME/CYCLE) 






(0) 


2ins 


1 


(1) 


8 ms 


2 


(2) 


16 ms 


3 


(3) 


24 ms 


4 


(4) 


38 ms 


5 


(5) 


56 ms 


6 


(6) 


68 ms 


7 


(7) 


80 ms 


8 


(8) 


100 ms 


9 


(9) 


250 ms 


10 


(A) 


500 ms 


11 


(B) 


800 ms 


12 


(C) 


Is 


13 


(D) 


3s 


14 


(E) 


5s 


IS 


(F) 


8s 



6 ms 

24 ms 

48 ms 

72 ms 

114 ms 

168 ms 

204 ms 

240 ms 

300 ms 

750 ms 

1.5 s 

2.4 s 

3s 

9s 

15 s 

24s 



NOTE: Envelope rates are based on a 1 .0-MHz 02 clock. For other 02 
frequencies, multiply the given rate by 1 MHz/02. The rates refer to the 
amount of time per cycle. For example, given an ATTACK value of 2, 
the ATTACK cycle would take 16 ms to rise from zero to peak ampli- 
tude. The DECAY/RELEASE rates refer to the amount of time these 
cycles would take to fall from peak amplitude to zero. 
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Figure 11-14. Envelope Rates 
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VOICE 2 

Registers $07-$0D control Voice 2 and are functionally identical to registers $00-$06 
with these exceptions: 



f-j 1. When selected, SYNC synchronizes Oscillator 2 with Oscillator 1. 

I I 2. When selected, RING MOD replaces the Triangle output of Oscillator 2 with 

the ring modulated combination of Oscillators 2 and 1 . 



VOICE 3 

Registers $0E-$14 control Voice 3 and are functionally identical to registers $00-$06 
with these exceptions: 

1. When selected, SYNC synchronizes Oscillator 3 with Oscillator 2. 

2. When selected, RING MOD replaces the Triangle output of Oscillator 3 with 
the ring modulated combination of Oscillators 3 and 2. 

Typical operation of a voice consists of selecting the desired parameters: fre- 
quency, waveform, effects (SYNC, RING MOD) and envelope rates, then gating the 
voice whenever the sound is desired. The sound can be sustained for any length of time 
and terminated by clearing the gate bit. Each voice can be used separately, with 
independent parameters and gating, or in unison to create a single, powerful voice. 
When used in unison, a slight detuning of each oscillator or tuning to musical intervals 
creates a rich, animated sound. 

FILTER 

FC LO/FC HI (REGISTERS $15,$ 1 6) 

Together these registers form an 1 1-bit number (bits 3-7 of FC LO are not used) which 
literally controls the Cutoff (or Center) Frequency of the programmable Filter. The 
approximate Cutoff Frequency ranges from 30 Hz to 12 KHz. 

RES/FILT (REGISTER $17) 

Bits 4-7 of this register (RES0-RES3) control the resonance of the filter. Resonance is a 
peaking effect which emphasizes frequency components at the Cutoff Frequency of the 
Filter, causing a sharper sound. There are sixteen resonance settings ranging linearly 
from no resonance (0) to maximum resonance (15 or $F). Bits 0-3 determine which 
signals will be routed through the Filter: 

FILT I (Bit 0): When set to a zero. Voice 1 appears directly at the audio output and the 
Filter has no effect on it. When set to a one. Voice 1 will be processed through 
the Filter and the harmonic content of Voice 1 will be altered according to the 
selected Filter parameters. 
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FILT 2 (Bit I): Same as bit for Voice 2. 
FILT 3 (Bit 2): Same as bit for Voice 3. 
FILTEX (Bit 3): Same as bit for External audio input (pin 26). 

MODE/VOL (REGISTER $18) 

Bits 4-7 of this register select various Filter mode and output options: 

LP (Bit 4): When set to a one, the Low-Pass output of the Filter is selected and sent to 
the audio output. For a given Filter input signal, all frequency components below 
the Filter Cutoff Frequency are passed unaltered, while all frequency components 
above the Cutoff are attenuated at a rate of 12 dB/Octave. The Low-Pass mode 
produces full-bodied sounds. 

BP (Bit 5): Same as bit 4 for the Bandpass output. All frequency components above 
and below the Cutoff are attenuated at a rate of 6 dB/Octave. The Bandpass mode 
produces thin, open sounds. 

HP (Bit 6): Same as bit 4 for the High-Pass output. All frequency components above 
the Cutoff are passed unaltered, while all frequency components below the Cutoff 
are attenuated at a rate of 12 dB/Octave. The High-Pass mode produces tinny, 
buzzy sounds. 

3 OFF (Bit 7): When set to a one, the output of Voice 3 is disconnected from the direct 
audio path. Setting Voice 3 to bypass the Filter (FILT 3 = 0) and setting 3 OFF 
to a one prevents Voice 3 from reaching the audio output. This allows Voice 3 to 
be used for modulation purposes without any undesirable output. 



NOTE: The Filter output modes ARE additive and multiple Filter modes 
may be selected simultaneously. For example, both LP and HP modes 
can be selected to produce a Notch (or Band Reject) Filter response. In 
order for the Filter to have any audible effect, at least one Filter output 
must be selected and at least one Voice must be routed through the Filter. 
The Filter is, perhaps, the most important element in SID as it allows the 
generation of complex tone colors via subtractive synthesis (the Filter is 
used to eliminate specific frequency components from a harmonically rich 
input signal). The best results are achieved by varying the Cutoff Fre- 
quency in real-time. 
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Bits 0-3 (VOL0-VOL3) select I of 16 overall Volume levels for the final composite 
audio output. The output volume levels range from no output (0) to maximum 
volume (15 or $F) in sixteen linear steps. This control can be used as a static 
volume control for balancing levels in multi-chip systems or for creating dynamic 
volume effects, such as Tremolo. Some Volume level other than zero must be 
selected in order for SID to produce any sound. 
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MISCELLANEOUS 

POTX (REGISTER $19) 

This register allows the microprocessor to read the position of the potentiometer tied to 
POTX (pin 24), with values ranging from at minimum resistance, to 255 ($FF) at 
maximum resistance. The value is always valid and is updated every 512 02 clock 
cycles. See the Pin Description section for information on pot and capacitor values. 

POTY (REGISTER $ I A) 

Same as POTX for the pot tied to POTY (pin 23). 

OSC 3/RANDOM (REGISTER $IB) 

This register allows the microprocessor to read the upper 8 output bits of Oscillator 3. 
The character of the numbers generated is directly related to the waveform selected. If 
the Sawtooth waveform of Oscillator 3 is selected, this register will present a series of 
numbers incrementing from to 255 ($FF) at a rate determined by the frequency of 
Oscillator 3. If the Triangle waveform is selected, the output will increment from up 
to 255, then decrement down to 0. If the Pulse waveform is selected, the output will 
jump between and 255. Selecting the Noise waveform will produce a series of random 
numbers, therefore, this register can be used as a random number generator for games. 
There are numerous timing and sequencing applications for the OSC 3 register; how- 
ever, the chief function is probably that of a modulation generator. The numbers 
generated by this register can be added, via software, to the Oscillator or Filter 
Frequency registers or the Pulse Width registers in real-time. Many dynamic effects can 
be generated in this manner. Siren-like sounds can be created by adding the OSC 3 
Sawtooth output to the frequency control of another oscillator. Synthesizer "Sample 
and Hold" effects can be produced by adding the OSC 3 Noise output to the Filter 
Frequency control registers. Vibrato can be produced by setting Oscillator 3 to a 
frequency around 7 Hz and adding the OSC 3 Triangle output (with proper scaling) to 
the Frequency control of another oscillator. An unlimited range of effects are available 
by altering the frequency of Oscillator 3 and scaling the OSC 3 output. Normally, when 
Oscillator 3 is used for modulation, the audio output of Voice 3 should be eliminated (3 
OFF = 1). 

ENV 3 (Registers I C) 

Same as OSC 3, but this register allows the microprocessor to read the output of the 
Voice 3 Envelope Generator. This output can be added to the Filter Frequency to 
produce harmonic envelopes, WAH-WAH, and similar effects. "Phaser" sounds can be 
created by adding this output to the frequency control registers of an oscillator. The 
Voice 3 Envelope Generator must be Gated in order to produce any output from this 
register. The OSC 3 register, however, always reflects the changing output of the 
oscillator and is not affected in any way by the Envelope Generator. 
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EQUAL-TEMPERED 
MUSICAL SCALE VALUES 



MUSIC NOTE VALUES 

Figure 1 1-15 contains a complete list of Note#, actual note, and the values to be stored 
into the HI FREQ and LOW FREQ registers of the sound chip to produce the indicated 
note. 
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The table in Figure 11-15 lists the numerical values which must be stored in the SID 
Oscillator frequency control registers to produce the notes of the equal-tempered musical 
scale. The equal-tempered scale consists of an octave containing twelve semitones 
(notes): C,D,E,F,G,A,B and C#,D#,F#,G#,A#. The frequency of each semitone is 
exactly the 12th root of 2 (\^^) times the frequency of the previous semitone. The 
table is based on a 02 clock of 1.02 MHz. Refer to the equation given in the Register 
Description for use of other master clock frequencies. The scale selected is concert 
pitch, in which A-4 = 440 Hz. Transpositions of this scale and scales other than the 
equal-tempered scale are also possible. 

Although the table in Figure 11-15 provides a simple and quick method for 
generating the equal-tempered scale, it is very memory inefficient as it requires 192 
bytes for the table alone. Memory efficiency can be improved by determining the note I 

value algorithmically. Using the fact that each note in an octave is exactly half the |j 

frequency of that note in the next octave, the note look-up table can be reduced from 
ninety-six entries to twelve entries, as there are twelve notes per octave. If the twelve 
entries (24 bytes) consist of the 16-bit values for the eighth octave (C-7 through B-7), 
then notes in lower octaves can be derived by choosing the appropriate note in the eighth 
octave and dividing the 16-bit value by two for each octave of difference. As division by 
two is nothing more than a right-shift of the value, the calculation can easily be 1 | 

accomplished by a simple software routine. Although note B-7 is beyond the range of U 

the oscillators, this value should still be included in the table for calculation purposes (the 
MSB of B-7 would require a special software case, such as generating this bit in the 
CARRY before shifting). Each note must be specified in a form which indicates which 
of the twelve semitones is desired, and which of the eight octaves the semitone is in. 
Since 4 bits are necessary to select one of twelve semitones and 3 bits are necessary to 
select one of eight octaves, the information can fit in one byte, with the lower nybble 
selecting the semitone (by addressing the look-up table) and the upper nybble being 
used by the division routine to determine how many times the table value must be 
right-shifted. 
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Figure 11-15. Music Note Values 



MUSI 


CAL NOTE 


OSCILLATOR 


FREQ 


NOTE 


OCTAVE 


DECIMAL 


HI 


LOW 





C-0 


268 


1 


12 


1 


C#-0 


284 


1 


28 


2 


D-0 


301 


1 


45 


3 


D#-0 


318 


1 


62 


4 


E-0 


337 


1 


81 


5 


F-0 


358 


1 


102 


6 


F#-0 


379 


1 


123 


7 


G-0 


401 


1 


145 


8 


G#-0 


425 


1 


169 


9 


A-0 


451 


1 


195 


10 


A#-0 


477 


1 


221 


11 


B-0 


506 


1 


250 


16 


C-1 


536 


2 


24 


17 


C#-l 


568 


2 


56 


18 


D-1 


602 


2 


90 


19 


D#-l 


637 


2 


125 


20 


E-1 


675 


2 


163 


21 


F-1 


716 


2 


204 


22 


F#-l 


758 


2 


246 


23 


G-1 


803 


3 


35 


24 


G#-l 


851 


3 


83 


25 


A-1 


902 


3 


134 


26 


A#-l 


955 


3 


187 


27 


B-1 


1012 


3 


244 


32 


C-2 


1072 


4 


48 


33 


C#-2 


1136 


4 


112 


34 


D-2 


1204 


4 


180 


35 


D#-2 


1275 


4 


251 


36 


E-2 


1351 


5 


71 


37 


F-2 


1432 


5 


152 


38 


F#-2 


1517 


5 


237 


39 


G-2 


1607 


6 


71 


40 


G#-2 


1703 


6 


167 


41 


A-2 


1804 


7 


12 


42 


A#-2 


1911 


7 


119 


43 


B-2 


2025 


7 


233 


48 


C-3 


2145 


8 


97 


49 


C#-3 


2273 


8 


225 


50 


D-3 


2408 


9 


104 


51 


D#-3 


2551 


9 


247 


52 


E-3 


2703 


10 


143 


53 


F-3 


2864 


11 


48 


54 


F#-3 


3034 


11 


218 


55 


G-3 


3215 


12 


143 


56 


G#-3 


3406 


13 


78 
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Figure 1 1-15. Music Note Values (continued) 



MUSICAL NOTE 


OSCILLATOR FREQ 


NOTE 


OCTAVE 


DECIMAL 


HI 


LOW 


57 


A-3 


3608 


14 


24 


58 


A#-3 


3823 


14 


239 


59 


B-3 


4050 


15 


210 


64 


C-4 


4291 


16 


195 


65 


C#-4 


4547 


17 


195 


66 


D-4 


4817 


18 


209 


67 


D#-4 


5103 


19 


239 


68 


E-4 


5407 


21 


31 


69 


F-4 


5728 


22 


96 


70 


F#-4 


6069 


23 


181 


71 


G-4 


6430 


25 


30 


72 


G#-4 


6812 


26 


156 


73 


A-4 


7217 


28 


49 


74 


A#-4 


7647 


29 


223 


75 


B-4 


8101 


31 


165 


80 


C-5 


8583 


33 


135 


81 


C#-5 


9094 


35 


134 


82 


C-0 


9634 


37 


162 


83 


C#-0 


10207 


39 


223 


84 


D-0 


10814 


42 


62 


85 


F-5 


11457 


44 


193 


86 


F#-5 


12139 


47 


107 


87 


G-5 


12860 


50 


60 


88 


G#-S 


13625 


53 


57 


89 


A-5 


14435 


56 


99 


90 


A#-5 


15294 


59 


190 


91 


B-5 


16203 


63 


75 


96 


C-6 


17167 


67 


15 


97 


C#-6 


18188 


71 


12 


98 


D-6 


19269 


75 


69 


99 


D#-6 


20415 


79 


191 


100 


E-6 


21629 


84 


125 


101 


F-6 


22915 


89 


131 


102 


F#-6 


24278 


94 


214 


103 


G-6 


25721 


100 


121 


104 


G#-6 


27251 


106 


115 


105 


A-6 


28871 


112 


199 


106 


A#-6 


30588 


119 


124 


107 


B-6 


32407 


126 


151 


112 


C-7 


34334 


134 


30 


113 


C#-7 


36376 


142 


24 


114 


D-7 


38539 


150 


139 


115 


D#-7 


40830 


159 


126 


116 


E-7 


43258 


168 


250 
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MUSICAL NOTE 



OSCILLATOR FREQ 



NOTE 



OCTAVE 



DECIMAL 



HI 



LOW 



117 


F-7 


45830 


179 


6 


118 


F#-7 


48556 


189 


172 


119 


G-7 


51443 


200 


243 


120 


G#-7 


54502 


212 


230 


121 


A-7 


57743 


225 


143 


122 


A#-7 


61176 


238 


248 


123 


B-7 


64814 


253 


46 



Figure 1 1-15. Music Note Values (continued) 
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LOCATION 



54293 
54294 
54295 



54296 



FILTER SETTINGS 



CONTENTS 



Low cutoff frequency (0-7) 

High cutoff frequency (0-255) 

Resonance (bits 4-7) 
Filter voice 3 (bit 2) 
Filter voice 2 (bit 1) 
Filter voice 1 (bit 0) 
High pass (bit 6) 
Bandpass (bit 5) 
Low pass (bit 4) 
Volume (bits 0-3) 



Figure 1 1-16. Filter Settings 
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INTRODUCTION 

Besides being a calculator and a data manipulator, the Commodore 128 is a communica- j 

tor. Through the various connecting ports, it can transmit and receive information to 

many different kinds of peripheral equipment. Because of the variety of devices, each 

must have its unique access codes and specific instructions (software). This chapter 

includes the details of each connection and the associated technique of communicating '-J 

with various devices. 

I f 

INPUT/OUTPUT PORTS U 

Most of the connections are considered as input and output because information is r. 

transmitted in both directions. These connections include the Commodore Serial Port for j ( 

the disk drive(s) and printer(s), the User Port for external communication with modems, '~-' 

an expansion port for additional memory, a Datassette connector for a tape storage 
device, two monitor ports for both the composite video and the RGBI monitors, a TV 
connector, and game ports for various control devices such as joysticks, paddles and 
graphics tablets. The port pinout details begin on page 394. 






DISK DRIVE 

The disk drive is the most popular information storage device today. It stores programs 1- 

and data as magnetic signals on a floppy disk of flexible plastic coated with iron oxide. 
Information (characters, letters and numbers) represented by a series of binary digits is j i 

magnetically impressed upon the disk in one of thirty-five concentric ring tracks. Each [J 

ring is divided into 17 to 21 sectors each. Each ring can store about 5000 bytes per 
track. A 1541 disk drive has a capacity of about 170K. The 1571 disk drive is - 

double-sided, so a disk formatted on the 1571 holds twice as much data, about 340K. i 

FORMATTING A DISK ^ ^ 

Blank disks from the factory are not assigned tracks or sectors. A disk must be uJ 

formatted by your computer/disk drive according to the disk operating system. You 
cannot store anything on a brand-new disk until this process, called Formatting or 
newing, is completed. The Commodore disk drive has built-in microprocessors that 
properly organize a blank disk when instructed to do so by the computer. The eighteenth 
track is used as a directory for the disk drive. All the addresses for all the blocks (over 
600) are stored on track 18 as the Block Allocation Map, or more simply the directory. 
Prior to formatting a disk, decide on an identification name and a two-digit code. 
Select a name of up to 16 characters that will help identify your disk. For example, the 
disk name could be your name, or a topic such as games. The two-digit code can be almost 
any letter-number combination. This code immediately alerts the disk drive whenever 
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you change disks — so, for your own protection, try to assign each disk a unique code. 
The format command for CI 28 mode is as follows: 



HEADER "disk name", Ixy,D0,ON U8 

For C64 or CI 28 modes, use: 

r^ OPEN 15,8,15, "NO:diskname, xy" 

i i 

' * Note that xy is any two-digit code you select, such as 01, 45, W3, 40, or WD. 

The after the D or N represents the default drive number for a single disk drive or the 
p first drive of a dual drive unit where both share a common device number. The 8 in each 

i i, statement represents the device number. A second drive would be set to number 9, a 

third drive to 10, etc. With a single drive, the HEADER command can simply be: 



HEADER"disk name",Ixy 

The formatting process typically takes about 80 seconds on the 1541 disk drive, 
and considerably less on the 1571 drive. Once this operation is completed, this disk can 
be used for storing programs and data. Do not format it again — otherwise everything 
saved on it will be erased. To simply "wipe" an already formatted disk, use the above 
instructions but do not include the comma followed by an identification number. This 
process will maintain the original format, use the new name and wipe the directory 
clean — a process considerably faster than total formatting. 

The OPEN command establishes a communication link between the computer and 
a specific device number. Disk drives are factory set as device number 8 and can be 
converted to device 9, 10, 11 or 12. See your disk drive manual for details. 

To verify you have properly formatted the disk, see the section below on reading 
the directory. 

SAVING PROGRAMS 

The saving process for storing programs on a disk does not remove the program from 
the computer. It simply "copies" the program or file from the computer onto the disk in 
the disk drive. Nothing is lost in the process. BASIC programs are saved to a formatted 
disk with the following commands: 

C128 or C64 SAVE"program name",8 

C 1 28 only DSAVE' 'program name" 

DSAVE"program name",D0,U9 

(if the drive is device number 9). 

In CI 28 mode, machine language programs or binary files can be saved through 
these BASIC commands: 

BSAVE"filename",Bb,Ps TO Pe 

or BSAVE"filename",D0,U9,Bb,Ps TO Pe 

(if the drive is device number 9). 
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In these formats: |_j 

"b" is the memory bank number (0 through 15) _ 

"s" is the starting address j 

"e" is the ending address L 

EXAMPLE: 

] 

BSAVE"filename",B2,P3584 TO P4096 Li 

This saves the binary file named "filename" from memory bank 2, in the range of 
memory between 3584 to 4096 decimal. j | 

The following command saves a BASIC program in either CI 28 or C64 modes: '--' 

SAVE "filename", 8 

I ! 

where 8 represents the device number. [J, 

REPLACrNG A FILE OR PROGRAM i 

When re-saving a program under the same filename, you must use the at sign (@) in the 
SAVE command format, as follows: 

In BASIC 7.0: DS AVE" ©program name" ! I 

In BASIC 2.0: SAVE"@0:program name",8 

The @ symbol tells the computer to store this program in place of the one of the > i 

same name. Without this symbol, the disk drive will not allow tiie new program to be jj 

stored. Note that during the replace process, the new program is saved first, then the old 
one is automatically deleted and the directory updated. Use VERIFY to make sure you 
are saving correctly. j 

VERIFYING A PROGRAM OR FILE 

You may want to verify that a program was accurately saved on the disk. The VERIFY |J 

command compares the program in memory with the program on the disk. If the 
programs are identical byte for byte, an OK message is displayed. 

In BASIC 7.0, use the following: 1 | 

DVERIFY"filename" 
or r, 

DVERIFY"filename",D0,U9 { j 

The first command above verifies a program using a single disk drive assigned as Unit 8, 

and the second command above verifies a program using a single disk drive assigned as - 

unit 9. M 

In 2.0 BASIC, use: 

VERIFY"filename",8 r j 

or VERIFY"filename",8,l U 
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(to verify the program from the memory location from which it was SAVEd, primarily 
machine language programs). 

After your program has been saved and verified, it is stored on your disk for future 
use. 



THE DIRECTORY 



Once a disk is formatted, it has a directory, or catalog listing of the files stored on the 
I 1 disk. Prior to loading a program, you may want to view the directory to find out exactly 

I '' what is stored on the disk. When you call for the directory, the screen displays the disk 

name and identification number followed by a list of programs or files presently stored. 
r-| Of course, a newly formatted disk will display only its name and number. To see the 

/ I directory, use the commands listed below. 

In BASIC 7.0, use the following: 

rj DIRECTORY 

I ( or CATALOG 

or CATALOG D0,U9 

p or DIRECTORY D0,U9 (for a dual disk drive, device number 9) 

I The program in memory is not affected by this command. 

In BASIC 2.0, use the following command: 

n LOAD"$0",8:LIST 

This command erases the resident program. The is optional with a single-drive 
unit. 

To print a hard copy of a directory, you must use the BASIC 2.0 method. You 
must first open a channel to the printer. This is covered below in the section Output to a 
Printer. 

RETRIEVING PROGRAMS OR 
FILES FROM DISKS 

Once you have files or programs stored on a disk, you retrieve them with an appropriate 
version of the LOAD command. 

In BASIC 7.0, use the following command: 

DLOAD'Tilename" 

or DLOAD'Tilename", D0,U9 
(for disk drive unit 9, drive 0) 

To retrieve a program or binary file saved by the BSAVE command or by the 
machine language monitor, use the following BASIC 7.0 command: 

BLOAD'Tilename' ' ,Bb,Ps 
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or BLOAD"filename",D0,U9,Bb,Ps 
(for disk drive unit 9, drive 0) 

where b is the bank number and s is the starting address. 
In BASIC 2.0, use the following command formats: 



u 

Q 



To load a BASIC program: L0AD"filename",8 j ; 

To load a machine language program: L0AD"filename",8,l |J 

The relocate flag is either a 1 or a 0, which is the default value. The 1 tells the 

computer to LOAD from the point where it was SAVEd. j [ 



CREATING AND STORING FILES || 

kfile is a series of related data: characters, numbers and letters. Anything stored on the 

disk is considered a file. A program is a specific type of file that can be executed or run. ) j 

Data files are files that contain raw data used by a program. These files are classified as Li 

either sequential, relative, user or random. The directory lists all the files and indicates 

the type of file: PRG for program, SEQ for sequential file, REL for relative file and j | 

USR for user files. [J 

A program is a file that contains operating instructions for the computer. A 

sequential" file is a series of data stored in sequence and can be read only in sequential ^ 

order. A relative file is a file stored in sequential order and can be accessed directly at | 

any location using a pointer. ' *-^ 

The creation of a sequential file is initiated with an OPEN statement. A file is 

OPENed with the following information: j [ 

■ File number: through 255; 15 is reserved for special commands and error 
checking. i t 

■ Device number: default is 8 for a disk drive; 4 for a printer (4-30 are available i ( 
for serial bus devices). 

■ Channel number: through 255; the line of communication established between 

devices (also known as secondary address) | 

Additional (optional) information may also be specified with quotes: 

■ Drive number followed by a colon: default is for a single drive; 1 may be j f 
specified on a dual drive. ^~^ 

■ Filename: the name of the file, up to 16 characters. 

■ Filetype: SEQ = sequential, PRG = program, REL = relative, USR = user ] [ 

■ Operation: (R = read, W = write) u_/ 

The following command: r ] 

OPEN HI, 8, 12,"0:NAME, S,W" Li 



n 
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opens file number 111 on device number 8, using channel 12. The file is opened to 
default drive 0, with the filename "NAME," as a sequential file. The W specifies that a 
write operation will take place. To store data, it is "written" on the disk. Data is 
retrieved by "reading" the disk. 

Enter, save and run the following programs as sample routines to create, save and 
read a sequential file. See your disk drive manual for more information. 



1 1 


10 




11 


m 


20 


I 


25 




30 




40 




50 


1 1 


60 



REM STORE DATA 

REM NOTE PROGRAM STOPS WHEN YOU RESPOND WITH 

OPEN 5,8,5, "EXAMPLE,S,W" 

DO 

INPUT "NAME OF A FRIEND" ;N$ 

PRINT#5,N$ 

IF N$ = "END"THEN CLOSE 5:END 

LOOP 



'END". 



n 



NOTE: In C128 mode, the Commodore 128 has a set of disk input/ 
output commands. These include the DLOAD and DSAVE commands 
ah-eady described, as well as the DOPEN, DCLOSE and other com- 
mands. See the BASIC 7.0 Encyclopedia in Chapter 2 or your disk drive 
manual for details on any of these commands. 



i \ 



Line 20 tells the disk drive to open a sequential file for writing data. Line 30 
obtains the information from the keyboard by requesting it on the screen. The PRINT# 
statement in line 40 specifies the file number where the information is to be written. 
Line 40 is the statement that actually writes the data to the channel and creates the 
contents of the file. Line 50 also puts a recognizable end-of-file marker — the word 
"end" at the end of the file. Line 50 closes the file after all data has been written. 

Here's a program that reads the data from the sequential file you just created: 

10 REM RETRIEVE HLES 

20 OPEN 6,8,6,"EXAMPLE,S,R" 

25 DO 

30 INPUT#6,L$ 

40 IF L$ = ' 'END' 'THEN CL0SE6:END 

50 PRINT L$ 

60 LOOP 

Line 20 opens a channel to the sequential file called EXAMPLE for reading. Once 
the end item is found, the file is properly closed. As each item is retrieved using the 
INPUT# statement, it is printed to the screen with a simple PRINT statement. Any 
sequential file in which all writing has been completed and which is already closed can 
be opened only as a read file; it cannot be written to unless an APPEND operation is 
specified or the @ prefix is used. 

Files can be expanded in size with the BASIC 7.0 APPEND command as follows: 
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APPEND#7, "EXAMPLE" b 

This command opens the file called "EXAMPLE." Any data sent to it in a PRINT#7 
statement will be appended. Any file number may be specified as long as the PRINT file j [ 

number matches the APPEND file number. '-' 

Once all the data is sent, the channel is closed with 

DCL0SE#7 1 j 

In BASIC 2.0, use this command: 

OPEN7,8,7, "0:EXAMPLE,A" j 

The letter A allows subsequent PRINT# statements to enter data at the end of the 
file "Example." This BASIC 2.0 technique also requires a CLOSE statement: CL0SE7. 

I 

OTHER FILES ^ 

C128 BASIC includes several direct disk drive housekeeping commands including 
SCRATCH, RENAME, CONCAT, COPY and COLLECT as well as a relative file j 

conunand RECORD. Note that these operations are also available in the C64 mode if '-' 

combined with an OPEN statement on channel 15. See your CI 28 System Guide 
Encyclopedia or disk drive manual for details. \ i 

In addition, see your disk drive manual for details on relative files, random files [j 

and direct program access to the disk drive microprocessor via channel 15. 



CHANGING THE DISK DRIVE 
DEVICE NUMBER 






The disk drive device number is usually 8, but it can be changed to be device 9, 10, or \ i 

1 1 by either a hardware or software change. The following command changes your drive |J 

to unit 9 through software until power is turned off: 

OPEN15,8,15:PRINT#15,"M-W"CHR$(119)CHR$(0)CHR$(2) 
CHR$(41)CHR$(73):CLOSE15 

The 1571 has a device number switch on the back. 



il 






OUTPUT TO A PRINTER 

1 1 

Your Commodore 128 computer transmits data over the serial port to many different l^ 

styles of printers. The most popular Commodore printers today are the daisy wheel and 
dot matrix types. The daisy wheel system uses metal or plastic molded letters similar to ^ ) 

those on a typewriter and produces the finest impressions. The fingers that hold these ! I 

characters are mounted on a center post, and the wheel resembles a daisy flower. The 
printer head spins the wheel until the correct letter is in position behind a hammer, 
which presses it against a ribbon onto the paper. \ 

The more versatile svstem is the dot matrix. Using a column of metal pins, a L 
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series of dots is impressed on paper through an inked ribbon as the printer head moves 
across the page. The pattern of dots is based upon the binary code of each character. 
The infinite number of potential dot patterns makes it possible to print any style 
character imaginable from italics to Japanese depending only upon the printer's internal 
software (firmware). 

Although many printer manufacturers claim their system is compatible with the 
Commodore 128 computer, if Commodore does not authorize the use, a special printer 
interface may be required. Printers cited as Centronics parallel or Serial do not directly 
match any of the Commodore computer ports. Commodore does not support any third- 
party printers or printer interfaces. The Commodore Serial Port is unique and not the 
same as the RS232 Serial Port, which many printer manufacturers specify. 

The Commodore computer can display 512 characters. The second set of 256 
includes both upper and lower case letters; the first includes upper case only with 
graphics. This is possible by using identical codes accessed separately. Consequently, 
only Commodore dot matrix printers are preprogrammed to print all the available 
Commodore characters. Owing to these differences, Commodore's ASCII codes are not 
Ij identical to the true ASCII standard. Therefore, special modifications are required when 

interfacing with non-Commodore equipment. 

In order to operate a printer, a line of communication with the computer must be 
opened using the OPEN statement. The printer is usually device number 4, though often 
switch selectable to 5. The command: 
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I \ 
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OPEN 3,4 

establishes a link to the printer as device number 4. The first number can be any 
number between 1 and 255. Numbers beyond 128 force a line feed after a carriage return. 

PRINTING A PROGRAM LISTING 

The following commands will produce a printed listing: 
OPEN3,4:CMD3:LIST 

The CMD command redirects all screen output to the printer. Any subsequent 
output is sent to the printer until turned off with: 

PRINT#3:CLOSE3 

These statements are necessary to clear the channel and ensure that all commands 
have been properly sent to the printer. 



NOTE: To print a listing with double spacing, a line feed can be forced 
using a file number greater than 127 such as: 



OPEN131,4:CMD131:LIST:PRINT#131:CLOSE131 
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PRINTING A TYPED LINE 

A PRINT# command to an opened print file number outputs the associated data to the 
printer. The following commands output whatever is typed: 

OPEN3,4:PRINT#3,"TYPE ANYTHING" 

After RETU RN is depressed, the line is sent to the printer and anything 
under quotes is printed on paper. 

PRINTING THROUGH A PROGRAM 



10 


OPEN 3,4,7 


20 


DO UNTIL L = 5 


25 


IF L=0THEN30 :ELSE rNPUTA$:GOTO40 


30 


INPUT"PLEASE TYPE";A$ 


40 


PRINT#3,A$ 


50 


L=L+1 


60 


LOOP 


70 


CL0SE3 



This is the beginning of a simple word processor and could be expanded into a 
complex system through printer control. 

CONTROLLING YOUR PRINTER 



PRINT#3, CHR$(27)CHR$(33) 
or PRINT#3, CHR$(27)"!" 

and turned off with: 

PRINT#3, CHR$ (27)CHR$(34) 

assuming channel 3 was previously opened. 



U 



Lj 



U 



Instructions to a printer require a PRINT# statement and can be mixed with the 

PRINT statement for video display. The following program prints five lines of text for . . 

each PRINT# statement while using the screen display to obtain the input: ( 

u 

\ 

Li 

u 



Each printer capability (such as lower case characters, line feed, double width charac- 
ters, reverse characters, dot graphics and special print fonts) is controlled by sending the , 
proper control code from the computer. Depending upon the printer being used, there J 
are two ways of sending code — either via the CHR$ function or the secondary address. 
Standard codes are sent via the BASIC CHR$(X) function. ASCII codes under 27 
are generally reserved for printer codes (such as 14 for the double width feature). Codes | 
over 27 represent specific keyboard characters. Printer control codes over 27 (e.g., 145) t..^ 
are preceded with the ESCape code 27. Some systems will accept CHR$(27) followed 
by either CHR$(X) or the equivalent character within quotes. Thus, boldface type T/ 
represented by Code 33 could be turned on with: I ( 



II 
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Many word processors can accommodate special printer controls with at least one 
of these methods. Refer to your printer and word processing manuals for the technique 
of sending control characters to your printer. 

The alternate method of sending control codes to a printer is via the secondary 
address in the OPEN statement. An OPEN statement without a secondary address 
defaults to 0. Hence OPEN3,4 is the same as OPEN3,4,0. Generally a secondary 
address of 7 will cause the printer to print with upper case and lower case characters: 



OPEN3,4,7 



Other secondary addresses are often available and will perform various duties in 
accordance with your printer's design. See your manual for specifics. Most word 
processors allow the use of secondary addresses as embedded codes. 

n The following program will open a channel to a sequential file on disk, read data 

/ i and output to a printer: 



10 


OPEN 3,8,3,"EXAMPLE,S,R" 


20 


OPEN 4,4,0 


25 


DO 


30 


INPUT#3,L$ 


40 


IF U = "END"THEN80ELSE50 


50 


PRINT#4,L$ 


60 


PRINT L$ 


70 


LOOP 


80 


CLOSE4:DCLOSE3:END 



OUTPUT TO A MODEM 



l~l A modem is a device used to transmit and receive data across telephone lines. 

' i Generally, a computer uses an RS232 port to communicate with the external 

world. Commodore's RS232C Port (also known as the User Port) is a variation of the 
p RS232 standard port. The RS232 has to 5 TTL voltage levels rather than the standard 

I j plus/minus 12 volts. 

The OPEN statement for the modem (device 2) sets up the parameters to match the 
p., speed (baud rate) and format (number of data and stop bits) of the host computer by 

sending a Control Register code. A second required code, the Command Register code, 

defines the parity, duplex and handshake. For example: 

OPEN3,2,0,CHR$(6)CHR$(1 12) 

opens a channel to the User Port (device #2) and establishes a 300-baud rate, 8-bit 
word, single stop bit (Control Register (6)), even parity and half duplex (Command 
Register (112)). See Figure 12-1, the Control Register Map, and Figure 12-2, the 
Command Register Map. 
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THE RS-232 CHANNEL 



u 



The RS-232 capabilities can be accessed from either BASIC or machine language. 
The BASIC commands INPUT# and GET# are used to fetch data from the receiving 
buffer while PRINT# and CMD place data into the transmitting buffer. 

The RS-232 Kemal routines run under the control of the 6526 CIA #2 device 
timers and interrupts. The 6526 chip generates NMI (Non-Maskable Interrupt) requests 
for RS-232 processing. This allows background RS-232 processing to take place during 
BASIC and machine language programs. There are built-in hold-off s in the Kemal, ) j 

cassette and serial bus routines to prevent the disruption of data storage or transmission ^ 

by the NMIs that are generated by the RS-232 routines. During cassette or serial bus 
activities, data can not be received from RS-232 devices. But because these hold-offs 
are only local, (assuming you're careful about your programming) no interference 
should result. '^ 

There are two buffers in the Commodore 128 memory to help prevent the 
loss of data when transmitting or receiving RS-232 information. \ I 

The Commodore 128 RS-232 I/O buffers consist of two first-in/first-out (FIFO) Li 

buffers, each 256 bytes long. In C128 mode, the RS-232 I/O buffers are permanently 
allocated. The input buffer is located between 3072 and 3327 ($OCOO-$OCFF). The j , 

output buffer is located between 3328 and 3583 ($ODOO-$ODFF). You cannot harm \J 

program storage by opening and closing the RS-232 channel as can happen with the 
Commodore 64. By permanently allocating the buffers in a fixed location, no "OUT OF 
MEMORY" error can occur, and your program in memory will not get "stepped on." ) 
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OPENING THE RS-232 CHANNEL 

Only one RS-232 channel should be open at any time; a second OPEN statement will 
cause the buffer pointers to be reset. Any characters in either the transmit buffer or the 
receive buffer will be lost. 

Up to 4 characters can be sent in the filename field. The first two are the control 
and command register characters; the other two are used for user-defined, non-standard 
baud rates. Baud rate, parity and other options can be selected through this feature. 

No error checking is done on the control word to detect a nonimplemented baud 
rate. Any illegal control word will cause the system output to operate at a very slow rate 
(below 50 baud). 

BASIC SYNTAX \ i 

OPEN lfn,2,0"<control reg.> <command reg.> <opt baud low> <opt baud high>" 
The logical file number (Ifn) then can be any number from 1 through 255. But be 
aware of the fact that if you choose a logical file number that is greater than 127, then a | ; 

line feed will follow all carriage returns. ^-^ 

THE CONTROL REGISTER { { 

The Control Register is a single-byte required to specify the baud rates and other RS-232 |j 
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options. Select the parameters you want from the Control Register Map (Figure 12-1) 
by placing the proper bit value in binary form. A selection, for example, from left to 
right of two stop bits, 7-bit word and 1200-baud rate yields: 

1010 1000 (in binary), which is decimal 168 ($A8) and results in 
OPEN 3,2,0,CHR$(168) 



defining these parameters. 



128 64 32 16 8 4 2 



STOP BITS — I 

0-1 STOP BIT 
1-2 STOP BITS 



WORD LENGTH • 



BIT 


DATA 
WORD LENGTH 


6 


5 








8 BITS 





1 


7 BITS 


1 





6 BITS 


1 


1 


5 BITS 



UNUSED 











BAUD RATE 














USER RATE 













50 BAUD 













75 












110 





1 








134.5 





1 







150 





1 







300 





1 






600 












1200 











1800 [Nl] 











2400 [Nl] 











3600 (Nl] 




1 






4800 [Nl] 




1 






7200 [Nl] 




1 






9600 [Nl] 




1 






19200 [Nl] 



Figure 12-1. Control Register Map 



THE COMMAND REGISTER 

The Command Register is a single byte that defines parity, duplex and handshaking. 
Select the parameters from the Command Register Map in Figure 12-2 by creating the 
binary code and converting it to a decimal value. Thus: 
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OPEN3,4,0,CHR$(168)CHR$(32) 

specifies odd parity, full duplex. A baud rate other than those listed in the Control 
Register Map is also selectable by choosing 0000 for bits through 3 in the Control 
Register and including this rate in the OPEN statement as two bytes following the 
Command Register. 

The "opt baud low" and high byte values are calculated from the desired 
baud rate as a function of the system frequency (1.022727E6 for the USA NTSC 
system or 0.985248E6 PAL European system). Divide the frequency by the desired 
rate. Divide this in half and subtract 100. This represents a two-byte decimal number. 
The high value is the number of times it can be divided by 256. The remainder is the 
low byte. 



BSiaBIIIIIlQS 



PARITY OPTIONS- 



BIT 
7 


BIT 
6 


BIT 
5 


OPERATIONS 


- 


- 





PARITY DISABLED, NONE 
GENERATED/RECEIVED 








1 


ODD PARITY 
RECEIVER/TRANSMITTER 





1 


1 


EVEN PARITY 
RECEIVER/TRANSMITTER 


1 





1 


MARK TRANSMITTED 
PARITY CHECK DISABLED 


1 


1 


1 


SPACE TRANSMITTED 
PARITY CHECK DISABLED 



DUPLEX- 



0-FULL DUPLEX 
1-HALF DUPLEX 

UNUSED 
UNUSED 
UNUSED 



I- HANDSHAKE 

0-3 LINE 
1-X LINE 



Figure 12-2. Command Register Map 
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EXAMPLE: 

1000 Baud: Divide the system frequency by the baud rate: 

1022727/1000=1022.727 

Divide by 2 and subtract 100: 1022.727/2 - 100 = 41 1 .3635 (or rounded up to 412) 

Convert this into two byte values: Division by 256 results in 1 with a remainder of 
' i 156. The following statement therefore defines a 1000-baud, 7-bit, single stop bit, odd 

parity, full duplex: 

OPEN3,2,0,CHR$(32)CHR$(32)CHR$(156)CHR$(1) 

where the Control Register value in binary is 00100000 and the Command Register in 
binary is 00100000. 
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NOTE: In a C64 BASIC program, the RS-232 OPEN command should be 
performed before creating any variables or arrays because an automatic 
CLR is performed when an RS-232 channel is OPENed owing to the 
allocation of 512 bytes at the top of memory. This is not the case in C128 
mode, since the RS-232 I/O buffers are permanently allocated. 



GETTING DATA FROM THE 
RS-232 CHANNEL 

The Commodore 128 receiver buffer ($0C00-$0CFF) will hold up to 255 characters befoi« 
overflowing. This is indicated in the RS-232 status word ST. If an overflow occurs, sub- 
sequent characters are lost. Keep the buffer as clear as possible. To receive data at high 
speeds, use machine language routines or use the FAST command to process at 2MHz 
with the 80-column screen (in CI 28 mode only). 

Use GET# with the file number corresponding to the OPEN statement. Machine 
code Kemal entries include BASIN and GETIN. 

SENDING DATA TO THE 
RS-232 CHANNEL 

When sending data, the output buffer ($0D00-$0DFF) can hold 255 characters before a 
full buffer hold-off occurs. The system will wait in the CHROUT routine until trans- 
mission is allowed or the RUN/STOP and RESTORE keys are used to 
recover the system. 

Use CMD or PRINT# with the proper file number to send data. Acceptable 
Kemal entries include BSOUT (CHROUT). 

CLOSING THE RS-232 CHANNEL 

Use CLOSE followed by the file number to close the RS-232 channel. Qosing the file discards 
all data in the buffers at the time of execution, stops all transmitting and receiving and sets 
the RTS and transmitted data lines high. In C64 mode (only) CLOSE removes both buffers. 
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NOTE: 


Care should be taken to ensure all data is 


transmitted before 


closing the channel. A way to check this from BASIC 


is: 


10 


DO 




20 


LOOP WfflLE PEEK (2575) and 3 




30 


CLOSE Ifn 




Location 2575 is the RS-232 "ENABL" location. 





Table 12-1 defines the User Port RS-232 channel lines. 



(6526 DEVICE #2 Loc. $DDOO-$DDOF) 


PIN 


6526 








IN/ 




ID 


ID 


DESCRIPTION 


EU 


ABV 


OUT 


MODES 


C 


PBO 


Received Data 


(BB) 


Sin 


IN 


1 2 


D 


FBI 


Request to Send 


(CA) 


RTS 


OUT 


1*2 


E 


PB2 


Data Terminal Ready 


(CD) 


DTR 


OUT 


1*2 


F 


PB3 


Ring Indicator 


(CE) 


RI 


IN 


3 


H 


PB4 


Received Line Signal 


(CF) 


DCD 


IN 


2 


J 


PBS 


Unassigned 


( ) 


XXX 


IN 


3 


K 


PB6 


Clear to Send 


(CB) 


CTS 


IN 


2 


L 


PB7 


Data Set Ready 


(CO 


DSR 


IN 


2 


B 


FLAG2 


Received Data 


(BB) 


s,„ 


IN 


1 2 


M 


PA2 


Transmitted Data 


(BA) 


Sout 


OUT 


1 2 


A 


GND 


Protective Ground 


(AA) 


GND 




1 2 


N 


GND 


Signal Ground 


(AB) 


GND 




1 23 



MODES: 

1. 3-Line Interface (S|„,S,„„GND). 

2. X-Line Interface. 

3. User Available Only (Unused/unimplemented in code). 

* These lines are held high during 3-Line mode. 

Table 12-1. User Port Lines 



U 

U 



1 I 



u 
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U 
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[7] [6] [5] [4] [3] [2] [1] [0] (Machine Lang. — RSSTAT) 

:_PARITY ERROR BIT 
: FRAMING ERROR BIT 



-RECEIVER BUFFER OVERRUN BIT 
-RECEIVER BUFFER— EMPTY 
(USE TO TEST AFTER A GET#) 
-CTS SIGNAL MISSING BIT 
-UNUSED BIT 

-DSR SIGNAL MISSING BIT 
-BREAK DETECTED BIT 



Figure 12-3. RS-232 Status Register 
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NOTES to Figure 12-3: 

The RS-232 Status Register can be read with these statements. 
If the STATUS = 0, then no error has been detected. 
S = PEEK (2580): PRINT S : POKE 2580,0 
If the RS-232 status is read by BASIC with the above statements or by 
using the KERNAL READST routine, the RS-232 status word is cleared 
when you exit. If multiple uses of the STATUS word are necessary, the 
S variable above should be assigned to another variable. For example: 

SR = S: REM ASSIGNS S TO SR 

The RS-232 status is read (and cleared) only when the RS-232 channel 
was the last external I/O used. 



n 



n 



SAMPLE BASIC PROGRAM 
USING RS-232 CHANNEL 

This simple terminal program works in both C128 and C64 modes: 

10 REM SIMPLE DUMB TERMINAL EMULATOR 

20 REM THIS PROGRAM REQUIRES A MODEM 

30 OPEN5,2,3,CHRS(6)+CHR$(0) 

40 DIMF%(255),T%(255) 

50 FORJ=32T064:T%{J)=J:NEXT 

60 T%(13)=13:T%(20)=8:RV=18:CT=0 

70 FORJ=65TO90:K=J+32:T%(J)=K:NEXT 

80 FORJ=91T095:T%(J)=J:NEXT 

90 FORJ=193T0218:K=J-128:T%(J)=K:NEXT 

100 T%(146)=16:T%(133)=16 

110 T%(137)=3:T%(134)=17:T%(138)=19 

120 FORJ=0TO255 

130 K=T%(J) 

140 IFK<>0THENF%(K)=J:F%(K+128)=J 

150 NEXT 

160 PRINT" "CHRS(147) 

170 GET#5,AS 

180 IFAS=""ORST<>0THEN220 

190 PRINT" "CHRS(157);CHRS(F%(ASC(A$))); 

200 IFF%(ASC(A$) )=34THENPOKE212,0 

210 GOTO170 

220 PRINTCHRS(RV)" "CHR$ ( 157 ) ;CHR$ ( 146 ) ; .-GETAS 

230 IFA$<>""THENPRINT#5,CHRS(T%(ASC(A$) ) ) ; 

240 CT=CT+1 

250 IFCT=8THENCT=0:RV=164-RV 

260 GOTO170 



ZERO-PAGE MEMORY LOCATIONS AND 
USAGE FOR RS-232 SYSTEM INTERFACE 

The zero-page RS-232 storage locations for both CI 28 and C64 modes are as follows: 

$00A7-INBIT— Receiver input bit temp storage. 
$00A8-BITCI— Receiver bit count in. 
$00A9-RINONE— Receiver flag start bit check. 
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All the above zero-page locations are used locally and are given only as a guide to 
understand the associated routines. These cannot be used directly by the BASIC or 
Kemal-level programmer to do RS-232-type programming functions. The system RS-232 
routines must be used. 

NONZERO-PAGE MEMORY LOCATIONS AND 
USAGE FOR RS-232 SYSTEM INTERFACE 

The general (nonzero-page) RS-232 storage locations for C128 mode are as follows: 
(The addresses in parentheses are for C64 mode.) 



u 



$OOAA-RIDATA — Receiver byte buffer/assembly location. ^ 

$OOAB-RIPRTY— Receiver parity bit storage. 

$00B4-BITTS— Transmitter bit count out. j j 

$00B5-NXTBIT— Transmitter next bit to be sent. U 

$00B6-RODATA — ^Transmitter byte buffer/disassembly location. 



il 



u 



U 



$0A10($0293)-M51CTR— Pseudo 6551 Control Register (see Figure 12-1). 

$0A11($0294)-M51CDR— Pseudo 6551 Command Register (see Figure 12-2). 

$0A12($0295)-M51AJB— Two bytes following the Control and Command Registers in j j 

the fde name field. These locations contain the user-defined baud rate for the start L- 

of the bit test during the interface activity, which, in turn, is used to calculate baud rate. 

$0A14($0297)— RSSTAT— The RS-232 Status Register (see Figure 12-3). , 

$0A15($0298)-BITNUM— The number of bits to be sent/received. I 

$0A16($0299)-BAUDOF— Two bytes that are equal to the time of one bit cell (based on ^ 

system clock/baud rate). 

$0A18($029B)-RIDBE— The byte index to the end of the receiver FIFO buffer. 

$0A19($029C)-RroBS— The byte index to the start of the receiver FIFO buffer. 

$OA1A($029D)-RODBS— The byte index to the start of the transmitter FIFO buffer. 

$OA1B($029E)-RODBE— The byte index to the end of the transmitter FIFO buffer. i , 

$0A0F($02Al)-ENABI^-Holds current active interrupts in the CIA #2 ICR. When bit ^ 

4 is turned on, the system is waiting for the Receiver Edge. When bit 1 is turned 
on, then the system is receiving data. When bit is turned on, then the system is 
transmitting data. '^ I 



u 



OUTPUT TO A SCREEN 

The most common form of computer output (called soft copy) is a display tube that 
displays luminescent dots on a screen controlled by electrical signals. Although the 
television is a specialized monitor and limited by the dot density prescribed by FCC 
standards for proper reception, it is available in most homes and becomes a ready-to-use 
output device for the home computer. The CI 28 computer sends radio frequency signals , , 

through the TV port to the television's antenna and tuner. | 

Monitors for computers produce better-quality displays since they are direct-wired '— ' 
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and involve no tuners. The CI 28 includes a port to accept the traditional monitors as 
well as Commodore's 40-column 1702 color monitor. The CI 28 80-column color 
capability is enhanced with the new 40/80-column color monitor Model 1902. In 
this RGBI monitor, signals separately control each of the three color guns (red, green, 
blue) for maximum clarity and detail. 

The screen can be accessed as an input or output device through the OPEN 
command as device 3. 

OPEN 1,3 

The screen is the default output device on the CI 28. Typing on the keyboard (device 0) 
results in a screen character display output whenever the monitor is powered up. No 
special commands are normally required. However, once control is sent to another 
device, reversion to the screen may be desired. 

Control of the screen display is available primarily with the PRINT command; 
associated punctuation including the quote and the semicolon and common, BASIC 
functions including the TAB(X), SPC(X), and CHR$(X) as well as the POKE com- 
mand. In addition, there are color controls, sprite animation and graphics keys. 

If using the dual 1902 monitor or two separate 40- and 80-column monitors, it is 
possible to swap control between the two screens via the 40/80 switch or pressing 
the ESC and X keys. If one is used for text and the other for graphics, use the 
GRAPHIC command. 

The following command will also swap the display output device: 

PRINT CHR$(27)"X" 

In addition to a screen display, sound commands can be used through a Commodore 
monitor or the television speakers. See Chapter 11, Sound and Music. 



OUTPUT TO THE DATASSETTE 

Commodore programs and files can also be stored on tape cassette using a special 
recorder called the Datassette. Unlike most tape recorders, which store analog sinusoidal 
signals, the Datassette stores digital pulse signals that are more distinct, resulting in 
a reliable storage format. Compared to a disk storage system, tape is somewhat slower 
and limited to program and sequential files. Access to the files on tape is sequential. 

Just as DLOAD automatically loads a program from disk, LOAD loads a 
program from tape. Similarly SAVE and VERIFY automatically default to tape. A 
LOAD for machine code requiring a secondary address would be: 

L0AD"NAME",1,1 

Access to tape for sequential files is made with an OPEN statement to device 1: 

OPENl.l 

A secondary address of (default value) assumes the file is opened for reading 
(using INPUT# or GET#). A secondary address for writing (PRINT# statements) 
requires a 1 or 2, where 2 includes an end-of-tape marker. 
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OPENl , 1 ,2"nLENAME" 

The end-of-tape marker prevents searching for files beyond the data file you are looking 
for. It is written when the CLOSE command is given. 



NOTE: Do not connect the Datassette and the 1571 disk drive to the CI 28 
at the same time. If they are used at the same time, the data transfers may 
not be reliable. 



INPUT FROM THE 
CONTROLLER PORTS 

The CI 28 has two controller ports (numbered 1 and 2) that allow the use of control 
devices such as a mouse, joystick, paddle or light pen. Each game port will accept either 
one joystick, one mouse, or one paddle pair. A light pen can be plugged only into Port 1 . 

JOYSTICKS [J 

A digital joystick has five distinct switches. Four of the switches are used for direction 

and one is used for the fire button. The joystick switches are arranged as shown in } 

Figure 12-4. L 

(Top) 
FIRE 

(Switch 4) 

UP 
(Switch 0) 

LEFT RIGHT 

(Switch 2) i (Switch 3) i. j 

DOWN 

(Switch 1) 

Figure 12-4. Joystick Switch Arrangement 



These switches correspond to the lower 5 bits of the data in location 56320 or 
56321. Normally the bit is set to a 1 if a direction is not chosen or the fire button is not 
pressed. When the fire button is pressed, the bit (bit 4 in this case) changes to a 0. To 
read the joystick from C64 BASIC, the following subroutine should be used: 
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10 REM JOYSTICK READ ROUTINE FOR C128 OR C64 MODES 

20 JV=PEEK( 56321) 

30 IF (JV AND 15X15 THEN PRINT 15-(JV AND 15) 

40 FIRE=JV AND 16 

50 IF FIRE016 THEN PRINT"FIRE" 

60 GOTO 20 



NOTE: For the first joystick, set JV = PEEK (56320). 



The values for JV correspond to the joystick directions shown in Table 12-2. 



- 


JV EQUAL TO 


DIRECTION 





NONE 




1 


UP 




2 
3 
4 


DOWN 
LEFT 




5 


UP & LEFT 


-■ 


6 

7 
8 


DOWN & LEFT 
RIGHT 




9 


UP & RIGHT 


n 


10 


DOWN & RIGHT 



Table 12-2. Joystick Direction Values 



A machine language routine that accomplishes the same task is given in the 
section on shift and rotate instructions in Chapter 5, Machine Language on the 
Commodore 128. 

BASIC 7.0 includes special joystick functions. To determine the position of joystick 
N, PRINT JOY(N) returns the position of the joystick. A number between and 8 
inclusive specifies the relative position where is stationary and 1 through 8 represent 
clockwise positions. Values between 128 and 136 signify the fire button is pressed as 
well. Thus if JOY(2) returns 131 , it means joystick number 2 fires to the right (position 3). 

10 REM C128-MODE SPRITE-MOVE JOYSTICK ROUTINE 

20 SPRITE 1,1,7:REM ENABLE SPRITE 1 

30 MOVSPR 1,160,150:REM PLACE SPRITE 1 ON CENTER OF THE SCREEN 

40 DO 



50 

60 

70 

80 

90 

100 

110 

120 



DO 

A=J0Y(1)!REM GET JOYSTICK DIRECTION VALUE 

IF A=0 THEN LOOP:REM LOOP IF ZERO - THIS KEEPS SPRITE STATIONARY 

B=A:REM SET B EQUAL TO A 

Z=(A-1)*45:REM CALCULATE ANGLE 

MOVSPR 1,5;Z:REM MOVE SPRITE 5 UNITS AT THE CALCULATED ANGLE 

A=J0Y(1):REM CHECK JOYSTICK VALUE AGAIN 
LOOP WHILE A=B:REM MOVE IN THE SAME DIRECTION WHILE NEW VAL=OLD JOY VALUE 



130 LOOP;REM OTHERWISE CHECK JOY VALUE AGAIN AND MOVE IN DIFFERENT DIRECTION 
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Using Boolean logic and the masking technique, a comparison can be made to 
determine whether the fire button was depressed: 



IF (JOY(N)AND 128)= 128 THEN PRINT"nRE" 

THE 1350 MOUSE 



120 
130 
140 
150 



SOUND 2,64000,60,0,1000, 16000, 3:REM FIRE 
COLOR 0,3: REM CHANGE SCREEN COLOR 



SLEEP 1 :REM DELAY 

COLOR 0,1: REM CHANGE SCREEN COLOR BACK 
160 BEND: REM END THE BEGIN/BEND STRUCTURE 
170 LOOP: REM DO IT AGAIN 



u 



u 



The Commodore 128 makes use of an additional new peripheral device known as a 
mouse. The Conmiodore mouse is a user interface that allows you to control the 
operations of a program, such as selecting menu or icon options, without the need to 
type on the keyboard. It attaches to the controller ports like a joystick, paddle or light 
pen. Programs that support a mouse usually have a pointer indicator to let you know 
where the mouse is pointing on the screen. To move the pointer on the screen, place the 
mouse on a flat surface and move it in the direction you want to move the pointer. Lift 
the mouse off the surface and the screen indicator remains stationary. The left hand 
button responds like a joystick fire button. The right hand button may have additional 
functions as specified by a particular software package. i i 

As far as BASIC is concerned, the mouse is supported by the JOY function, the M 

same way a joystick is controlled. The previous joystick program example, which 
moves a sprite on the screen, also works with the mouse. The Joystick Musician 
program in Chapter 1 1 also works with the mouse. Any BASIC program using the JOY t 

joystick function should operate with the Commodore mouse. U 

The mouse also works in C64 mode, the same way a joystick routine would in 
C64 mode. The previous C64 mode joystick example program supports the mouse in 
C64 mode. 

PADDLES 

A paddle is connected to both CIA-1 and the SID chip (MOS 6581 Sound Interface Device) U 

through a controller port. The paddle value is read via the SID registers 54297 ($D419) and 
54298 ($D41A). Paddles are not reliable when read from BASIC alone! The best way to 
use paddles, from BASIC or machine code, is to use a machine language routine (SYS 
to it from BASIC then PEEK the memory locations used by the subroutine). 
The following BASIC program moves a sprite with paddles: 

10 REM C128-MODE SPRITE-MOVE PADDLE ROUTINE [_ 

20 REM PLACE DUAL PADDLES IN CONTROLLER PORT A 

30 REM PADDLE 1 CONTROLS HORIZONTAL SPRITE MOVEMENT 

40 REM PADDLE 2 CONTROLS VERTICAL MOVEMENT 

50 SPRITE 1,1,7 

60 DO 

70 A=P0T(1):REM GET POSITION (X) OF PADDLE 1 

80 B=P0T(2):REM GET POSITION (Y) OF PADDLE 2 

90 PRINT A;B:REM PRINT VALUES 

100 MOVSPR 1,A,B:REM MOVE SPRITE 1 ACCORDING TO PADDLE VALUES 

110 IF (A>255) OR (B>255) THEN BEGIN:REM CHECK FOR FIRE BUTTON 
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LIGHT PEN 

The light pen input latches the current screen position into a pair of registers (LPX, 
LPY) on a low-going edge. The X position register 53267 ($D013) will contain the 8 MSB 
of the X position at the time of transition. Since the X position is defined by a 512-state 
counter (9 bits), resolution to two horizontal dots is provided. Similarly, the Y position 
is latched in its register 53268 ($D014), but here 8 bits provide single raster resolution 
within the visible display. The light pen latch may be triggered only once per frame, and 
subsequent triggers within the same frame will have no effect. Therefore, you must take 
several samples before turning the pen to the screen (three or more samples average), 
depending upon the characteristics of your light pen. The following program is a light 
pen draw routine in CI 28 mode: 



10 REM CI 28 MODE LIGHT PEN DRAW ROUTINE 

2 REM PLACE LIGHT PEN IN CONTROLLER PORT 1 

30 COLOR 0,2: COLOR 4, 2: COLOR 1,1: REM SELECT SCREEN COLORS 

40 GRAPHIC 1,1:REM SELECT BIT MAP MODE 



50 DO 
60 
70 
80 



X=PEN(0) :REM GET HORIZONTAL COORDINATE 
Y=PEN(1) :REM GET VERTICAL COORDINATE 
DRAW 1,X,Y :REM PLOT POINT 



90 LOOP :REM DO IT AGAIN 

100 : 

110 REM IF YOU LIKE THE DRAWING, 

12 REM BREAK THE PROGRAM AND 

130 REM SAVE IT AS A BINARY FILE 

140 REM FROM S2000-$3FFF. 



OUTPUT CONTROL TO 
ALL DEVICES 



Each peripheral device is identified by a device number, as hsted in Table 12-3. 



DEVICE 


DEVICE NUMBER 


SECONDARY ADDRESSES 


Keyboard 







Datasette 


1 


0,1,2 


Modem (RS232) 


2 





Screen 


3 


0,1 


Printer 


4 or 5 


0,7,etc 


Disk Drive 


8,9,10,11 


2-14,15 



Table 12-3. Device Numbers 

Serial devices can be numbered 4 through 30, but they usually conform to the 
above conventions. All devices can be accessed in a single OPEN statement by using 
an integer variable: 
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10 INPUT "SELECT DEVICE NUMBER ";D% 

20 INPUT "SELECT SECONDARY ADDRESS", •S% 

30 INPUT "NAME OF PILE OR CONTROL REGISTER" , -AS 

40 OPEN 9,D%,S%,AS 

50 GOSUB 80 

60 CLOSE 9 

70 END 

80 REM PLACE SUBROUTINE HERE 

90 RETURN 



THE INPUT/OUTPUT 

PINOUTS ^ 

THE SERIAL PORT [] 

The Serial Port is a daisy chain arrangement designed to let the Commodore 128 computer 

communicate with more than one device, such as Commodore disk drives and printers. 

Up to five devices can be connected at one time. The serial bus can transmit control ^ 

signals from the computer, send data onto the bus, and receive data from the bus. Data 

or control signals are routed to the proper device by opening a specific bus address I I 

ranging from 4 to 31. Typically, addresses 4 and 5 are reserved for printers, and jj 

addresses 8 through 11 are for the disk drive. 

Six lines are used in serial bus operation — three input and three output. The three , , 

input lines bring data, control and timing signals into the computer. The three output 
lines send data, control and timing signals from the computer to the external devices. 
See Hardware Specifications (Chapter 16) for details on the C128 serial bus protocol. 



SERIAL I/O 



PIN TYPE 



1 


SERIAL SRQIN 


2 


GND 


3 


SERIAL ATN IN/OUT 


4 


SERIAL CLK IN/OUT 


5 


SERIAL DATA IN/OUT 


6 


RESET 




Figure I2f-5. Serial Port Pinouts 



USER PORT (RS.232 CHANNEL) 

The User Port (RS-232 Channel) connects the Commodore 128 to the outside 
world, such as another Commodore computer. It is directly connected to the 6526 CIA 
#1 chip. Figure 12-6 shows the User Port pinouts. Table 12-4 defines the pinouts. 
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Figure 12^4. User Port Pinouts 



PIN 


DESCRIPTION 




TOP SIDE 


NOTES 


1 


GROUND 




2 


+ 5V 


(100 mA MAX.) 


3 


RESET 


By grounding this pin, the Conunodore 128 will do 
a cold start, resetting completely. The pointers to 
a BASIC program will be reset, but memory will 
not be cleared. This is also a RESET output for 
the external devices. 


4 


CNTl 


Serial port counter from CIA-1 (see CIA specs). 


5 


SPl 


Serial port from CIA-1 (see 6526 CIA specs). 


6 


CNT2 


Serial port counter from CIA-2 (see CIA specs). 


7 


SP2 


Serial port from CIA-1 (see 6526 CIA specs). 


8 


PC2 


Handshalcing line from CIA-2 (see CIA specs). 


9 


SERIAL 


This phi is connected to the ATN line of the serial 




ATNBS 


bus. 


10 


9 VAC + phase 


Connected directly to the Commodore 128 trans- 


11 


9 VAC-phase 


former (100 mA Max.). 


12 


GROUND 




BOTTOM SIDE 






A 


GROUND 


The Commodore 128 gives you control over Port 


B 


FLAG2 


B on CIA chip 1. Eight lines for input or output 


C 


PBO 


are available, as well as two lines for handshaking 


D 


FBI 


with an outside device. The I/O lines for Port B 


E 


PB2 


are controlled by two locations. One is the Port 


F 


PB3 


itself, and is located at 56577 ($DD01 HEX). 


H 


PB4 


Naturally you PEEK it to read an INPUT, or 


J 


PBS 


POKE it to set an OUTPUT. Each of the eight 


K 


PB6 


I/O lines can be set up as either an INPUT or an 


L 


PB7 


OUTPUT by setting the Data Direction Register 


M 


PA2 


properly. 


N 


GROUND 





Table 12-4. User Port Pin Descriptions 

The Data Direction Register has its location at 56579 ($DD03 hex). Each of the 
eight lines in the port has a bit in the 8-bit Data Direction Register (DDR) that controls 
whether that line will be an input or an output. If a bit in the DDR is a 1, the 
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corresponding line of the port will be an output. If a bit in the DDR is a 0, the 
corresponding line of the port will be an input. For example, if bit 3 of the DDR is set to 1 , 
then line 3 of the port will be an output. If the DDR is set like this: 



BIT #: 7 6 5 4 3 2 10 
VALUE: 1110 



Notice that the bit number for the DDR is the same number that is equal to 2 raised to a 
power to turn the bit value on. 



THE COMPOSITE 
VIDEO CONNECTOR 



u 



u 



lines 5, 4 and 3 will be outputs since those bits are I's. The rest of the lines will be 
inputs, since those lines are O's. 

To PEEK or POKE the User Port, it is necessary to use both the DDR and the port i j 

itself. jj 

Remember that the PEEK and POKE statements need a number from to 255. 
The numbers given in the example must be translated into decimal before they can be 
used. The value would be: I 

25 + 2'* + 2^ = 32 + 16 + 8 = 56 "" 



u 

(16 = 214 = 2x2x2x2, 8 = 213 = 2x2x2) 

The two other lines, flagl and PA2, are different from the rest of the User Port. [ 

These two lines are mainly for handshaking, and are programmed differently from 
port B. 

Handshaking is needed when two devices communicate. Since one device may run 
at a different speed than another device, it is necessary to give each device some way of L 

knowing what the other device is doing. Even when the devices are operating at the 
same speed, handshaking is necessary to communicate when data is to be sent, and if it 
has been received. The flagl line has special characteristics that make it well suited for 
handshaking. 

Flagl is a negative-edge-sensitive input that can be used as a general-purpose 
interrupt input. Any negative transition on the flag line will set the flag interrupt 
bit. If the flag interrupt is enabled, this will cause an Interrupt Request. If the 
flag bit is not enabled, it can be polled from the Interrupt Register under program control. 

PA2 is bit 2 of port A of the CIA. It is controlled like any other bit in the port. 
The port is located at 56576 ($DDOO). The Data Direction Register is located at 56578 
($DD02). 

For more information on the 6526, see the hardware chapter. 
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This DIN connector supplies direct audio and composite video signals. These can 
be connected to the Commodore monitor or used with separate components. This is the 
40-column output connector. Figure 12-7 shows the pinouts for the composite video I 

connector. Table 12-5 describes the pinouts. ^ 

U 
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Figure 12-7. Composite Video Connector Pinouts 



PIN 


TYPE 


NOTE 


1 


LUM/SYNC 


Luminance/SYNC output 


2 


GND 




3 


AUDIO OUT 




4 


VIDEO OUT 


Composite signal output 


5 


AUDIO IN 




6 


COLOR OUT 


Chroma signal output 


7 


NC 


No connection 


8 


NC 


No connection 



Table 12-5. Composite Video Connector Pin Descriptions 

THE RGBI 

VIDEO CONNECTOR 

The RGBI video connector is a 9-pin connector that supplies an RGBI (Red/Green/Blue/ 
Intensity) signal. This is the 80-column output. Figure 12-8 shows the RGBI pinouts. 
Table 12-6 defines the RGBI pinouts. 




Figure 12-8. RGBI Connector Pinouts 
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PIN SIGNAL 



1 


Ground 


2 


Ground 


3 


Red 


4 


Green 


5 


Blue 


6 


Intensity 


7 


Monochrome 


8 


Horizontal Sync 


9 


Vertical Sync 



u 



Table 12-6. RGBI Connector Pin Descriptions 

THE CASSETTE CONNECTOR [\ 

A 1530 Datassette recorder can be attached to the cassette port to store programs and 



information. Figure 12-9 shows the cassette port pinouts. Table 12-7 describes the 
pinouts 



1 2 3 4 S 6 



A B C D E F 
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Figure 12-9. Cassette Port Pinouts 



PIN 


TYPE 


A-1 


GND 


B-2 


+ 5V 


C-3 


CASSETTE MOTOR 


D-4 


CASSETTE READ 


E-5 


CASSETTE WRITE 


F-6 


CASSETTE SENSE 



u 



Table 12-7. Cassette Port Pin Descriptions 



THE CONTROLLER PORTS i | 

There are two controller ports, numbered 1 and 2. Each controller port can accept a 
joystick, mouse or game controller paddle. A light pen can be plugged only into Port 1 , the 
port closest to the front of the computer. Use the ports as instructed with the software. 
Figure 12-10 shows the Controller Port pinouts. Table 12-8 describes the pinouts. 

U 
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Figure 1 2*- 10. Controller Port Pinouts 



CONTROL PORT i 




CONTROL PORT 2 




PIN TYPE 


NOTE 


PIN 


TYPE 


NOTE 


1 JOYAO 




1 


JOYBO 




2 JOYAl 




2 


JOYBl 




3 JOYA2 




3 


JOYB2 




4 J0YA3 




4 


JOYB3 




5 POT AY 




5 


POT BY 




6 BUTTON A/LP 




6 


BUTTON B 




7 +5V 


MAX. 50mA 


7 


+ 5V 


MAX. 50mA 


8 GND 




8 


GND 




9 POT AX 




9 


POTBX 





Table 12-8. Controller Port Pin Descriptions 



n 



THE EXPANSION PORT 

Vhe expansion port connector is a 44-pin female edge connector accessing the comput- 
er's address and data buses. It accepts Commodore's preprogrammed game and utility 
software cartridges. As a parallel port, it can accept Commodore's IEEE peripherals 
with an IEEE interface for controlling instrumentation and other devices. RAM expan- 
sion modules will also connect to this port and accept the BASIC commands of FETCH, 
STASH and SWAP. ^ 

Figure 12-11 shows the expansion port pinouts. Table 12-9 describes the pinouts. 



I i 



B2ia>l9iS 171615141312 t1 10* 8 7 8 5 4 3 2 1 

■■■■■■■■■■■■■■■■■■■■■■ 



ZVXWVUTSRPNMLKJHFEDCBA 

(view of port from the back of the C1 28) 
Figure 1^1 1. Expansion Port Pinouts 
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PIN 


TYPE 


PIN 


TYPE 


1 


GND 


A 


GND 


2 


+ 5V 


B 


ROMH 


3 
4 
5 


+5V 

IRQ 

RAV 


C 
D 
E 


RESET 
NMI 

S02 


6 


Dot Clock 


F 


A15 


7 


I/Ol 


H 


A14 


8 


GAME 


J 


A13 


9 


EXROM 


K 


A12 


10 


1/0 2 


L 


All 


11 


ROML 


M 


AlO 


12 


BA 


N 


A9 


13 


DMA 


P 


A8 


14 


D7 


R 


A7 


15 


D6 


S 


A6 


16 


DS 


T 


AS 


17 


D4 


U 


A4 


18 


D3 


V 


A3 


19 


D2 


W 


A2 


20 


Dl 


X 


Al 


21 


DO 


Y 


AG 


22 


GND 


Z 


GND 



Table 12-9. Expansion Port Pin Descriptions 
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The Commodore 128 operating system controls, directly or indirectly, all functions of '-' 

your computer. The Commodore 128 operating system is housed in a ROM chip called 

the Kernal, which contains about 16K of machine language instructions. These instruc- j / 

tions make up the routines that control all the machine's functions — even the ones you i_] 

take for granted. For instance, the Kemal controls all input and output functions, 

including receiving the characters from the keyboard when you type, sending text to a , , 

printer, and displaying graphics and text on tfie screen. Every task performed by the | 

computer other than application program activities is controlled by the Kemal. The 

Kemal even manipulates and executes the application programs you load or type into 

your computer's memory. ] 1 

TAKING FULL ADVANTAGE OF THE [\ 

COMMODORE 128 OPERATING SYSTEM 



u 



The 16K of operating system instmctions contained in the Kemal are available for use 

with your own programs. Instead of "reinventing the wheel" and duplicating code, you 

can call (that is, use) these Kemal routines in your own programs. You do this through 

the Kemal Jump Table, which consists of a series of ROM entry points in which you L 

can call machine language routines already available in the Commodore 128 Kemal. By 

calling these routines, which handle the most fundamental functions of the computer, r 

you avoid duplicating code. This helps you utiHze your computer to its fullest potential. I 

The Kemal Jump Table also facilitates compatibility. If the Commodore 128 
operating system is modified or upgraded, which happens frequently in the microcom- 
puter industry, the entry points in the jump table are revised to reflect address changes 
of Kemal subroutines. The key to keeping applications programs compatible from one 
version of the operating system to another is to enter the operating system through the 
Kemal Jump Table. Instead of jumping directly to a subroutine (JSR), use the Kemal 
Jump Table as the entry point, since it contains the correct address vector to the 
specified routine, regardless of the version of the Kemal being used. If you always enter 
the operating system routines from the Kemal Jump Table, the address of the desired 
routine will always be reached. On the other hand, if you bypass the Kemal Jump Table 
and jump directly to the address where you think the routine resides, you may cause an 
error, because the starting point of the desired routine may have changed from one 
version of the operating system to another. 



u 
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HOW TO USE (CALL) 
^ THE KERNAL ROUTINES IN 

' YOUR OWN PROGRAMS 

I 1 Most of the system subroutines require specific parameters, or values, which must be 

loaded into the accumulator, X or Y index registers. Some Kemal subroutines require 

^ additional preparatory routines to be called before invoking the specific target routine. 

I I Each Kemal subroutine terminates with an RTS instruction that tells the microprocessor 

' 1 to return from the subroutine. Many of the Kemal routines return values that are placed 

in the accumulator, X or Y registers. Some even return error codes in the status register, 

1^ which can be acted on in your applications program. 

I ! Here is the procedure for calling a Kemal subroutine: 



i ! 



n 



n 



1. Place the necessary preparatory values in the required registers — either the A, 
X or Y registers. 

2. Enable the appropriate system configuration. For example, if the routine 
requires the Kemal to be present, invoke either configuration 12, 13, 14 or 15, 
since these make the Kemal available. Bank 15 is the default configuration. 

3. Call the subroutine with the JSR instraction, using the address of the jump 
vector as shown in the Kemal Jump Table in Figure 13-1. 

For example, the starting address of the routine ACPTR is stored, starting 
in location $FFA5. Actually, the operation code (opcode) for the JMP instrac- 
tion is stored at location $FFA5 and the address of the entry point of the 
routine is stored at locations $FFA6 and $FFA7. What really happens is that 
the JSR instraction in your application program transfers control to the jump 
table address ($FFA5, for example); then the JMP instraction at $FFA5 jumps 
to the subroutine at the address specified in locations $FFA6 and $FFA7. In 
other words, when you issue a JSR instraction to the Kemal Jump Table, you 
actually perform two jumps: one (JSR) to the jump table, and then a second 
jump (JMP) to the actual starting address of the routine. 

The routine terminates with an RTS instraction that is already part of the 
Kemal subroutine. Your application program resumes with the instraction 
immediately following the JSR instraction. 

4. Uponretumfromthesubroutine,checkthestatusregisterforanyerrorconditions.If 
an error condition is present, take precautions in your application 
program to handle the error and act on the value of the status register. 

Figure 13-1 is the C128 system vector and jump table that includes the 
name, address and function description of the operating system Kemal routines. 
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CI 28 SYSTEM VECTORS 



1. $FFEB SYSTEM 

2. $FFFA NMI 



;operating system vector (RAMI) 
;processor NMI vector 



3. $FFFC RESET 

4. $FFFE IRQ 



;processor RESET vector 
;processor IRQ/BRK vector 



CBM STANDARD KERNALJUMP 


TABLE CALLS 


1. 

2. 
3. 


$FF81 
$FF84 

$FF87 


JMPCINT 
JMPIOINTT 
JMP RAMTAS 


linit screen editor and devices 

init I/O devices 

init RAM and buffers 


4. 

5. 
6. 


$FF8A 
$FF8D 
$FF90 


JMP RESTOR 
JMP VECTOR 

JMP SETMSG 


;init indirect vectors (system) 
;init indirect vectors (user) 
jlcernal messages on/off 


7. 
8. 
9. 


$FF93 
$FF96 
$FF99 


JMP SECND 
JMPTKSA 
JMP MEMTOP 


;serial: send SA after LISTN 
;serial: send SA after TALK 
;set/read top of system RAM 


10. 
11. 

12. 


$FF9C 
$FF9F 

$FFA2 


JMP MEMBOT 
JMP KEY 
JMP SEITMO 


;set/read bottom of system RAM 

;scan lieyboard 

preserved) 


13. 
14. 
15. 


$FFA5 
$FFA8 
SFTAB 


JMP ACPTR 
JMP CIOUT 
JMPUNTLK 


;serial: byte input 
;serial: byte output 
;serial: send untalh: 


16. 
17. 
18. 


$FFAE 
$FFB1 
$FFB4 


JMP UNLSN 
JMP LISTN 
JMP TALK 


;serial: send unlisten 
;serial: send listen 
;serial: send tsSk 


19. 
20. 
21. 


$FFB7 
$FFBA 
$FFBD 


JMP READSS 
JMP SETLFS 

JMP SETNAM 


;read I/O status byte 
;set channel LA, FA, SA 
;set filename pointers 


22. 
23. 
24. 


$FFC0 
$FFC3 
$FFC6 


JMP (lOPEN) 
JMP (ICLOSE) 
JMP (ICHKIN) 


;open logical file 
;close logical file 
;set input channel 


25. 
26. 

27. 


$FFC9 
$FFCC 
$FFCF 


JMP (ICKOUT) 
JMP (ICLRCH) 
JMP (IBASIN) 


;set output channel 
;restore default channels 
;input from channel 


28. 
29. 
30. 


$FFD2 
$FFD5 
$FFD8 


JMP (IBSOUT) 
JMP LOAD 
JMP SAVE 


;output to channel 
;load from file 
;save to file 


31. 

32. 
33. 


$FFDB 
$FFDE 
$FFE1 


JMP SETTIM 
JMP RDTIM 
JMP (ISTOP) 


;set internal clock 
;read internal clock 
;scan STOP key 



u 
u 
u 
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34. $FFE4 JMP (IGETIN) 

35. $FFE7 JMP(ICLALL) 

36. $FFEA JMPUDTIM 



;read buffered data 
;close all fOes and channels 
;increnient internal clock 



37. $FFED JMPSCRORG 

38. $FFFO JMP PLOT 

39. $FFF3 JMPIOBASE 



;get current screen window size 
;read/set cursor position 
;read base address of I/O block 



NEW CI 28 KERNALJUMP TABLE CALLS 



1. $FF47 JMP SPIN SPOUT 


setup fast serial ports for I/O 


2. $FF4A JMP CLOSE ALL 

3. $FF4D JMPC64MODE 

4. $FF50 JMP DMA CALL 


,close all files on a device 
reconfigure system as a C64 
send command to DMA device 


5. $FF53 JMP BOOT CALL 

6. $FF56 JMP PHOENIX 

7. $FF59 JMPLKUPLA 


boot load program from disk 
init function cartridges 
search tables for given LA 


8. $FF5C JMPLKUPSA 

9. $FF5F JMP SWAPPER 
10. $FF62 JMPDLCHR 


search tables for given SA 
switch between 40 and 80 columns 
init 80-coI character RAM 


11. $FF65 JMPPFKEY 

12. $FF68 JMPSETBNK 

13. $FF6B JMPGETCFG 


program a function key 
set bank for I/O operations 
lookup MMU data for given bank 


14. $FF6E JMPJSRFAR 

15. $FF71 JMPJMPFAR 

16. $FF74 JMPINDFET 


gosub in another bank 

goto another bank 

LDA (fetvec),Y from any bank 


17. $FF77 JMPINDSTA 

18. $FF7A JMPINDCMP 

19. $FF7D JMPPRIMM 


STA (stavec),Y to any bank 
CMP (cmpvec),Y to any bank 
print immediate utility 



! I 



Figure 13-1. User-Callable Kernal Routines 



n 



Figure 13-2 lists the conventions used in the description of each Kernal subrou- 
tine. The figure is followed by descriptions of the CI 28 system vectors and Kernal 
subroutines. Included in each description are the subroutine name, call address, prepara- 
tory routines needed (if any), the registers affected, the error codes associated with each 
routine, how to use them and an example of each kernal subroutine call. 



n 
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USER CALLABLE 

KERNAL ROUTINE CONVENTIONS 



NOTE: Some Kemal I/O routines do not use these codes for error 
messages. Instead, errors are identifled using the Kemal READST routine. 



NUMBER 


MEANING 





Routine terminated by the STOP key 


1 


Too many open files 


2 


File already open 


3 


File not open 


4 


File not found 


5 


Device not present 


6 


File is not an input flle 


7 


File is not an output file 


8 


File name is missing 


9 


niegal device number 


41 


File read error 



Registers Affected: All registers, memory and flags used by the Kemal routine are 

listed here. 
Examples: An example of each Kemal routine is listed. 
Description: A short explanation of the function of the Kemal routine is given here. 

Figure 13-2. User-Callable Kemal Routine Conventions 







Call Address: This is the call address of the Kemal routine, given in hexadecimal. l^ 

Function Name: Name of the Kemal routine. 

Register: Registers, memory and flags listed under this heading are used to pass < , 

parameters to and from the Kemal routines. ii 

Preparatory Routines: Certain Kemal routines require that data be set up by prepara- 
tory routines before the target routine can be called. The necessary routines are 
listed here. 

Error Returns: A retum from a Kemal routine with the carry set indicates an error c- 

was encountered in processing. The accumulator will contain the number of the 
error. 

Error Codes: Below is a list of error messages that can occur when using the 
Kemal routines. If an error occurs during a Kemal routine, the carry bit of the 
accumulator is set, and the number of the error message is retumed in the 
accumulator. 
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CI 28 SYSTEM VECTORS 



i \ The vectors listed below, with the exception of the SYSTEM vector, are located not 

only in system ROM but in each RAM bank. The beginning and end of the system 
interrupt handlers are found in the top page ($FFxx) of all memory configurations as 
well. The reason is simple: An interrupt can occur anytime, from any memory configu- 
ration. The registers and memory configuration must be preserved prior to bringing the 
operating system into context to process the interrupt. They must similarly be restored 
Pj before control is finally returned to the interrupted code. Note that the system vectors 

i i are indirect jumps, and are not usually called by the user since they terminate with an 

RTI instruction, not an RTS instruction. In other words, they process interrupted events, 

r^ not subroutine calls. 

i ' 

1. $FFF8 SYSTEM ;operating system vector (RAMI) 

PI The SYSTEM vector and accompanying KEY string provide applications software 

I \ with a means of regaining system control after a hardware reset. With this vector, 

software may be protected from an otherwise unrecoverable situation. The KEY 
— string provides the distinction between a "warm" reset and a "cold" power-up. If 

I the system has just powered up, the KEY string is missing and thus the SYSTEM 

' vector is invalid; the CBM KEY is installed and the SYSTEM vector is set to C128 

mode. If the system was reset (i.e., KEY was found), the SYSTEM vector is 
n moved to common RAM at $02 and an indirect JMP is performed. In most cases, 

I 1 the user need only call lOINIT beore resuming control. The layout in RAM-1 is: 

$FFF5 'C ($43) 

p $FFF6 'B' ($42) 

I i $FFF7 'M' ($4D) 

$FFF8 SYSTEM vector low 

^ $FFF9 SYSTEM vector high 

For example, suppose a programmer set out to do some heavy-duty "hacking" 

using the built-in Monitor. Fully realizing the likelihood of losing control in a crash, 

P the programmer could redirect the SYSTEM vector to the Monitor itself and thus 

I \ regain control with minimal RAM loss, simply by pressing the RESET button. To 

accomplish this, the programmer would enter: 

P a. >1FFF8 00 13 :aim SYSTEM to $1300 

I I b. A 1300 JSR $FF84 :call lOINIT 

JMP $B000 :call Monitor 

j \ 2. $FFFA NMI ;processor NMI vector 

The Non-Maskable Interrupt (NMI) vector is activated whenever the processor 
^ NMI pin detects a negative edge. There are two possible sources of NMI's under 

I : normal conditions: the RESTORE key and RS-232 I/O. In the event of an 

i I NMI, the operating system disables IRQ's, saves the registers and current memory 
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3. $FFFC RESET ;processor RESET vector 

The processor RESET vector is activated whenever the system RESET signal is 
low. It is low at power-up, and is pulled low by pressing the RESET button. This 
signal effects not only the processor but most of the I/O devices found in the 
system. In fact, RESET is the one processor control signal that is shared between 
the two processors (8502 and Z80) of the C128. The Z80 gains initial (default) 
control of the system while the 8502 is held in a waiting state. When the 8502 
finally starts after a reset, the Kemal initialization routine START always receives 
control and immediately performs the following actions: 

1 . Brings the system map into context. 

2. Disables IRQ's. 

3. Resets the processor stack pointer. 

4. Clears decimal mode. 

5. Initializes the MMU. 

6. INSTALLS the Kemal RAM code. 



u 
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configuration on the stack, brings the system configuration (ROM's, I/O, RAMO) 
into context, and executes an indirect jump through the RAM vector located at 
$318. The system NMI handler clears the ICR register of CIA-2, fi-om which it 
determines the source of the interrupt. If it is from timer A, control passes to the \ \ 

RS-232 transceiver. If not, the RESTORE key is assumed, and for safety, 
the CBM convention of requiring the STOP key to be simultaneously de- 
pressed is checked. If the STOP key is depressed, all system indirect vectors are [ 
restored, lOINIT and CINT are called, and the SYSTEM_VECTOR (do not '-' 
confuse with the SYSTEM vector!) is taken. Control is returned upon restoration of 
the registers and memory configuration. NMI's may be disabled by causing an initial \ I 
NMI from timer A, but never reading the ICR to clear it, thus keeping the NMI [J 
signal grounded. 

Application software can intercept an NMI event by modifying either of the 
two RAM vectors mentioned above. The NMI indirect vector at $318 in common 
RAM will pass control whenever an NMI occurs. The SYSTEM-VECTOR, located 
at $A00 in RAMO, will pass control after STOP/RESTORE is detected and handled. 

For example, suppose a situation similar to the one illustrated previously for | I 

the SYSTEM vector occurs. To return control to the Monitor whenever STOP/ U 

RESTORE is detected, enter: 

a. >A00 00 BO :aim SYSTEM-VECTOR to Monitor | ( 

Similarly, to perform an action anytime an NMI occurs (e.g., RESTORE 
alone), use the NMI indirect. For example, increment the VIC border color when- 
ever you press RESTORE (or cause any other NMI). Enter: 

a. >318 00 13 :aim indirect to $1300 

b. A 1300 INC $D020 :change border color j, 

JMP $FF33 :retum from interrupt 
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Up to this point there is no provision for user code. The next two routines in the 
initialization path actually look for installed user code: 



( I 7. SECURE: Check and initialize the SYSTEM vector. 

' ^ 8. POLL: Check for a ROM cartridge. 

,«, POLL first scans for any installed C64 cartridges. They are recognized by 

; I either the GAME or EXROM signal being pulled low. If so, G064 is executed 

' ' (see the Kemal jump entry for details). Polling for C64 cartridges is actually 

redundant at this point since the Z80 processor, which powers up initially, did this 
n already. POLL then scans for installed C128 cartridges and function ROM's. They 

1 i are recognized by the existence of the C« key in any of the four function ROM 

slots (two internal, two external) and are polled in the order external low (16 or 
r^ 32KB), external high (16KB), internal low (16 or 32KB), internal high (16KB). 

i i The entire format is: 

$xOOO ->■ cold start entry 
$x003 —* warm start entry (unused) 
$x006 -^ ID. ($01-$FF) 
$x007 -» "CBM" key string 
^ where x = $8— or $C— . 

The ID of any C128 cartridge found is entered into the Physical Address Table 
(PAT) located at SAC1-SAC4. ID's must be non-zero. Cartridges may recognize 
each other by examining the PAT for particular ID's. An ID of 1 indicates an 
auto-start cartridge, and its cold start entry will be called immediately. All others 
will be called later (see PHOENIX jump), as will any auto-starters that RTS is to 
POLL. A cartridge can determine where it is installed by examining CURBNK, 
located at $ACO. Because it is possible for a cartridge to be called with interrupts 
1 1 enabled, the following diversion from the above format is recommended (the warm 

start entry is never called by the system): 



I $xOOO SEI 

I ' $x001 IMP STARTUP 

$x004 NOP 

$x005 NOP 



The balance of the CI 28 initialization is: 



^ 9. lOINIT: Initialize I/O devices. 

( ! 10. Check for STOP AND O keys. 

' > 11. RAMTAS: Initialize system RAM. 

12. RESTOR: Initialize system indirects. 

n 13. CINT: Initialize video displays. 

( \ 14. Enable IRQ's (except foreign systems). 

15. Dispatch. 

n lOINIT is perhaps the major function of the Reset handler. It initializes both CIA's 

( i (timers, keyboard, serial port, user port, cassette) and the 8502 port (keyboard. 
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LI 



cassette, VIC bank). It distinguishes a PAL system from an NTSC one and sets 
PALCNT ($A03) if PAL. The VIC, SID and 8563 devices are initialized, including 
the downloading of character definitions to 8563 display RAM (if necessary). The \ i 

system 60Hz IRQ source (the VIC raster) is started. lOINIT is callable by the user [j 

via the jump table. 

During initialization, the user may press certain keys as a means of selecting , . 

an operating mode. One key checked is the Commodore key O , indicating C64 | f 

mode is desired. While this key was scanned much earlier by the Z80 to speed '"-' 

the switchover to C64 mode, there is a redundant check for it here. The only other 
key scanned at this time is the STOP key, which signals a request by the user 
to power up into the Monitor utility. Note that control does not pass from the 
initialization process at this point; the Kemal needs to know if RAM TAS should be 
skipped. Only if the STOP key is depressed and this was a "warm" reset 
(vs. "cold" power-up) can RAMTAS be skipped. i ) 

RAMTAS clears all page-zero RAM, allocates the cassette and RS-232 
buffers, sets pointers to the top and bottom of system RAM (RAM-0), and 
installs the SYSTEM-VECTOR (discussed earlier under NMI) that points to BA- 
SIC cold start. Lastly it sets a flag, DEJAVU ($A02), to indicate to other routines 
that system RAM has been initialized. This is the difference between a "cold" 
and a "warm" system. If DEJAVU contains $A5, the system is "warm" and | / 

SYSTEM—VECTOR is valid. Many programmers debugging code need to recover jj 

from a system hang or crash via RESET but do not want RAM cleared. This 
is why the STOP key is scanned, RAMTAS is skipped, and the Monitor : , 

(rather than BASIC) is selected. RAMTAS is callable by the user via the jump \ 

table. 

RESTOR initializes the Kemal indirect vectors. This must be done before 
many system routines will function. Applications that complement the operating 
system via "wedges" must install them after they are initialized. RESTOR is user 
callable from the jump table (see also the VECTOR call). 

CINT is the Editor's initialization routine. Both 40- and 80-column display j 

modes are prepared, editor indirect vectors installed, programmable key definitions 
assigned, and the 40/80 key scnaned for default display determination. CINT is also 
a jump table entry. 

Finally, the IRQ's are enabled and control is passed to either BASIC ( 

initialization, G064 code, or the ML Monitor. BASIC will call the Kemal '-' 

PHOENIX routine upon the conclusion of its initialization, which will call any 
installed CI 28 cartridges (any ID) and attempt to auto-boot an application from | ' 

disk. o 

An initialization status byte, INIT_STATUS ($A04), marks the progress of 
the initialization process. It is cleared automatically at the beginning of the Reset \ i 

code, and as specific stages are completed, a particular bit is set. The layout is: [J 

B7 —*■ 8563 characters installed 
B6 -^ CINT performed 
BO -^ BASIC initialized 
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Any lOINIT calls, including Reset, will not result in 8563 character RAM initial- 
ization if B7 is set. Similarly, CINT will not initialize the keyboard matrix lookup 
tables and the programmable key definitions if B6 is set. This is how NMI's, for 
example, can call lOINIT and CINT without destroying users' setups. Finally, 
BASIC initialization must be complete before BO is set. This determines whether 
the IRQ handler, for example, should call the BASIC IRQ routines. Note that the 
following sequence of events should be performed for a BASIC programmer to 
recover from a crash via RESET : 

Hold down STOP key to enter Monitor. 
Press and release RESET button . 
Release STOP key. 
Enter: >A04 CI :re-enable BASIC IRQ. 
Enter: X :exit Monitor to BASIC. 

This sequence is necessary because INIT_STATUS was cleared by the reset, and 
the BASIC initialization was skipped, leaving BO reset. If BO had not been set, 
BASIC IRQ routines such as SOUND, PLAY, and SPRITE handlers would not 
have functioned, usually resulting in an apparent "hang." 



4. $FFFEIRQ ;processor IRQ/BRK vector 



This hardware vector is taken whenever the IRQ pin of the processor is pulled low, 
or the processor executes a BRK instruction. For proper operation an IRQ must 
occur sixty times every second [NTSC (60Hz) presents no problems, but adjust- 
ments have to be made for PAL (50Hz) systems]. The usual source of IRQ's in the 
CI 28 is the VIC raster, which is unleashed during system initialization by lOINIT. 
In the event of an IRQ or BRK, the operating system saves the registers and current 
memory configuration on the stack and brings the system bank (ROM's, I/O, 
] I RAMO) into context. The processor status at the time of interruption is then read 

fi-om the system stack to determine if the interrupt was an IRQ or a BRK. The C128 
uses the following code to accomplish this: 

TSX ;get stack pointer 

LDA $105,X ;retrieve processor status 
AND #$10 ;examine BRK flag 



If the BRK flag is set, control passes to the ML Monitor through the BRK 
indirect vector at $316, which usually points to the Monitor BREAK entry. Here 
the program counter (PC), processor status, registers, memory configuration and 
stack pointer are retrieved and displayed. 

If the BRK flag is 0, an IRQ is assumed and control passes through the IRQ 
indirect vector at $314, normally to the system IRQ handler. The following processes 
are then performed in the order shown: 
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1. IRQ's disabled. L 

2. Editor: split screen handler. 

3. Editor: clear VIC raster IRQ. \ ; 

4. IRQ's enabled. ij 

5. Editor: keyboard scan. 

6. Editor: VIC cursor blink. , 

7. Kemal: "jiffie" clock. j | 

8. Kemal: cassette switches. '-^ 

9. Kemal: clear CIA-1 ICR. 

10. BASIC: sprites, sounds, etc. 

1 1 . Retum from interrupt. 



ii 



As indicated in the preceding description, the C128 operating system uses the 
IRQ heavily. In particular, the Editor split screen handler has rather strict require- } j 

ments that programmers must recognize and accommodate. An all-text screen or a v_; 

fully bit mapped screen presents no particular problem, but a split text and bit map 
screen requires twice the IRQ frequency (two every sixtieth of a second). Thus, the \ i 

Editor (and consequently, IRQ-dependent applications) must distinguish between [J 

the "main" 60Hz IRQ and the "middle" IRQ. Only during the main IRQ will all 
the actions listed above be performed; the middle IRQ is only used by the Editor to 
split the screen. The Editor IRQ routine sets the carry flag to designate a main IRQ. ; 

Moreover, there is no margin in the timing requirements of a split screen. Program- '— ' 

mers should note the way the Editor uses the VIC during IRQ's and avoid direct VIC 
I/O if the Editor screen operations are enabled. There is a flag byte called GRAPHM, \ { 

located at $D8, which can be set to $FF to disable the Editor's use of the VIC. tj 

The Editor is also responsible for scanning the C128 keyboard. Programmers 
should note that SCNKEY has two indirect jumps, KEYLOG and KEYPUT, it , | 

takes during its execution. The keyboard is controlled via CIA-1 PRA, PRB, VIC i | 

register #47 (extended key matrix), and the 8502 port (bit 6 = CAPS LOCK). The '"' 

SCNKEY routine is callable from the jump table. 

The balance of the IRQ routines up to calling BASIC are self-explanatory. 
The Kemal software clock is maintained by UDTIM, which is in the jump table. 
The IRQ processing makes one last call to BASIC-IRQ ($4006), but only if 
INIT_STATUS bit is set indicating BASIC is ready to handle IRQs (this was 
discussed earlier in the RESET section). BASIC-IRQ is a heavy user of the VIC 
and SID, and the same precautions should be taken regarding direct VIC and SID 
I/O as with the Editor. BASIC_IRQ also utilizes a hold-off byte called IRQ-WRAP 
-FLAG. It is normally used by the system to block IRQ-ed IRQ calls, but can be 
set by the user with the effect of disabling the BASIC-IRQ handler. Alternatively 
you could clear bit of the INIT-STATUS byte as mentioned above and achieve 
the same result. 

The use of the IRQ indirect ($314) by an application usually requires more 
care than most other wedges for several reasons. The likelihood of an IRQ occur- 
ring while the wedge is being installed is greater, there exists the possibility that the 
user or some other software has abready wedged the vector, and usually it is 



u 



y 



l! 



n 



THE COMMODORE 128 OPERATING SYSTEM 413 



r 

' ' desirable for the system IRQ functions to continue normally (e.g., keyscan) as 

opposed to replacing them totally with our own (as we did with the NMI examples). 
|~J The following examples accomplish these objectives as well as masking out all but 

I 1 the main IRQ. First we must install our IRQ handler. This example converts the 

4 0/80 key into a SLOW/FAST key: 



' 1 

/ 1 


A 1302 


BIT $D011 


;test VIC reg 17 






BPL $1324 


;branch if wrong IRQ 


rj 




LDA $D505 


ipreparation 






ORA #$80 


;b7 of MMU MCR 






STA $D505 


;set for input 


r-i 




LDA $D011 


;assume FAST setup 


i i 




AND #$6F 


;blankVIC(RC8 = 0) 






LDX #$01 


;2MHz 


n 




BIT $D505 


;test 4 0/80 key 




BPL $131E 


;branch if down (FAST) 


1 i 




ORA #$10 


;unblank VIC 






DEX 


;lMHz 


n 


131E 


STX $D030 


;set speed 


i 1 




STA $D011 


;set blank bit 




1324 


IMF ($1300) 


;continue system IRQ 



Now we need a small routine to actually wedge our code into the system IRQ. The 
following code saves the current IRQ vector for our handler above to exit through 
and substitutes a pointer to our code: 



j~| A 1400 SEI ;prevent interruptions 

; I LDA $314 ;get current IR(3 Isb 

STA $1300 ;andsaveit 

J-, LDA $315 ;get current IRQ msb 

1 1 STA $1301 ;and save it 

' ^ LDA #$02 ;get our IRQ Isb 

STA $314 ;and substitute it 

rj LDA #$13 ;get our IRQ msb 

( \ STA $315 ;and substitute it 

CLI ;re-enable IRQ processing 

f-t RTS 

! I 

Enable the wedge by typing J 1400, that's all there is to it. Depressing the 

n Locking 40/80 key now puts you in FAST mode; releasing it SLOWS you 

down, and the keyscan, etc., continues to function. Note, however, that on this 



n 
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CBM STANDARD KERNAL CALLS 



The following system calls make up the set of standard CBM system calls for the 
Commodore 128 Personal Computer. Several of the calls, however, function somewhat 
differently or may require slightly different setups than C64 mode. This was necessary 
to accommodate specific features of the system, notably the 40/80 column windowing 
Editor and banked memory facilities. As with all Kemal calls, the system coniiguration 
(high ROM, RAM-0 and I/O) must be in context at the time of the call. 



PREPARATION: 




Registers: 


none 


Memory: 


system map 


Rags: 


none 


Calls: 


none 


RESULTS: 




Registers: 


.A used 




.X used 




.Y used 


Memory: 


init Editor RAM 




init Editor I/O 


Flags: 


none 


EXAMPLE: 




SEI 




JSR $FF81 


;initialize screen 


CLI 









split screen our code throws off the timing, making for an unattractive display. '— ^ 

There are really only three things to watch out for when toying with the CI 28 

system IRQ: First, be sure to keep the raster compare value on-screen to keep the \ { 

IRQ's happening (the best way is to keep RC8 zero as in example above); second, !_) 

never attempt to access the 8563 during an IRQ if there is any chance that it is in 

use; finally, be sure the source of the IRQ is being cleared. 



ij 



u 



u 



1. $FF81 CINT ;initialize screen editor and devices j / 

U 

!l 

U 



11 



\ 1 

CINT is the Editor's initialization routine. Both 40- and 80-column display j i 

modes are prepared, editor indirect vectors installed, programmable key definitions 
assigned, and the 4 0/80 key scanned for default display determination. CINT 
sets the VIC bank and VIC nybble bank, enables the character ROM, resets SID 
volume, places both 40- and 80-column screens and clears them. The only thing it 
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does not do that pertains to the Editor is I/O initialization, which is needed for IRQ's 
(keyscan, VIC cursor blink, split screen modes), key lines, screen background 
colors, etc. (see lOINIT). Because CINT updates Editor indirect vectors that are 
used during IRQ processing, you should disable IRQ's prior to calling it. CINT 
utilizes the status byte INIT_STATUS ($A04) as follows: 





$A04 bit 6 


= ^ Full initialization. 

(set INIT_STATUS bit 6) 
1 -» Partial initialization. 






(not key matrix pointers) 
(not program key definitions) 



CINT is also an Editor jump table entry ($C000). 
2. $FF84 lOINIT ;init I/O devices 



PREPARATION: 




Registers: 


none 


Memory: 


system map 


Flags: 


none 


Calls: 


none 


RESULTS: 




Registers: 


.A used 




.Xused 




.Y used 


Memory: 


initialize I/O 


Flags: 


none 


EXAMPLE: 




SEI 




JSR $FF84 


;initialize sys 


CLI 





lOINIT is perhaps the major function of the Reset handler. It initializes both 
CIA's (timers, keyboard, serial port, user port, cassette) and the 8502 port (key- 
board, cassette, VIC bank). It distinguishes a PAL system from an NTSC one and 
sets PALCNT ($A03) if PAL. The VIC, SID and 8563 devices are initialized, 
including the downloading of character definitions to 8563 display RAM (if neces- 
sary). The system 60Hz IRQ source, the VIC raster, is started (pending IRQs are 
cleared). lOINIT utilizes the status byte INIT_STATUS ($A04) as follows: 

$A04 bit 7 = -^ Full initialization. 

(set INIT_STATUS bit 7) 
= 1 -> Partial initialization. 

(not 8563 character definitions) 
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You should be sure IRQ's are disabled before calling lOINIT to avoid interrupts 
while the various I/O devices are being initialized. 



3. $FF87 RAMTAS ;init RAM and buffers 



/ 



I I 



PREPARATION: 




Registers: 


none 


Memory: 


system map 


Flags: 


none 


Calls: 


none 


RESULTS: 




Registers: 


.A used 




.X used 




.Y used 


Memory: 


initializes RAM 


Flags: 


none 


EXAMPLE: 




JSR $FF87 


;initialize systen 



U ' 



u 



u 



RAMTAS clears all page-zero RAM, allocates the cassette and RS-232 
buffers, sets pointers to the top and bottom of system RAM (RAM 0) and points 
the SYSTEM-VECTOR ($A00) to BASIC cold start ($4000). Finally, it sets a 
flag, DEJAVU ($A02), to indicate to other routines that system RAM has been 
initialized and that the SYSTEM-VECTOR is valid. It should be noted that the 
CI 28 RAMTAS routine does not in any way test RAM. 



U 



] I 
) ) 



4. $FF8A RESTOR ;init Kemal indirects 



O 



PREPARATION: 




Registers: 


none 


Memory: 


system map 


Flags: 


none 


Calls: 


none 


RESULTS: 
Registers: 


.A used 




.X used 




.Y used 


Memory: 


Kemal indirects restored 


Flags: 


none 



u 



u 



U 



U 
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EXAMPLE: 

SEI 

JSR $fT8A ;restore Kemal indirects 

CLI 

RESTOR restores the default values of all the Kemal indirect vectors from 
the Kemal ROM list. It does not affect any other vectors, such as those used by the 
Editor (see CMT) and BASIC. Because it is possible for an intermpt (IRQ or NMI) 
to occur during the updating of the interrupt indirect vectors, you should disable 
interrapts prior to calling RESTOR. See also the VECTOR call. 



i i 5. $FF8D VECTOR ;init or copy indirects 



PREPARATION: 




Registers: 


.X = adr (low) of user list 




.Y = adr (high) of user list 


Memory: 


system map 


Flags: 


.C = -» load Kemal vectors 




.C = 1 — » copy Kemal vectors 


Calls: 


none 


RESULTS: 




Registers: 


.A used 




.Yused 


Memory: 


as per call 


Flags: 


none 


EXAMPLE: 




LDX #save_lo 




LDY #save_hi 




SEC 




JSR $FF87 


;copy indirects to "save" 



VECTOR reads or writes the Kemal RAM indirect vectors. Calling VEC- 
TOR with the carry status set stores the current contents of the indirect vectors to 
the RAM address passed in the .X and .Y registers (to the current RAM bank). 
Calling VECTOR with the carry status clear updates the Kemal indirect vectors 
from the user list passed in the .X and .Y registers (from the current RAM bank). 
Intermpts (IRQ and NMI) should be disabled when updating the indirects. See also 
the RESTOR call. 
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6. $FF90 SETMSG ;Kemal messages on/off 



PREPARATION: 
Registers: 
Memory: 
Flags: 
Calls: 

RESULTS: 
Registers: 
Memory: 
Flags: 

EXAMPLE: 

LDA#0 
JSR $FF90 



.A = message control 

system map 

none 

none 

none 

MSGFLG ($9D) updated 

none 



;tum OFF all Kemal messages 



SETMSG updates the Kemal message flag byte MSGFLG ($9D) that deter- 
mines whether system error and/or control messages will be displayed. BASIC 
normally disables error messages always and disables control messages in Run 
mode. Note that the Kemal error messages are not the verbose ones printed by 
BASIC, but simply the I/O ERROR # message that you see when in the Monitor, 
for example. Examples of Kemal control messages are LOADING, FOUND, and 
PRESS PLAY ON TAPE. The MSGFLG control bits are: 



MSGFLG bit 7 = 1 
bit 6 = 1 



enable CONTROL messages 
enable ERROR messages 



7. $FF93 SECND ;serial: send SA after LISTN 



PREPARATION: 




Registers: 


.A = SA (secondary address) 


Memory: 


system map 


Flags: 


none 


Calls: 


LISTN 


RESULTS: 




Registers: 


.A used 


Memory: 


STATUS ($90) 


Hags: 


none 


EXAMPLE: 




LDA#8 




JSR $FF81 


;LISTN device 8 


LDA #15 




JSR $FF93 


;pass it SA #15 



u 



Lj 



u 
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u 
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* I 



'u 



n 



THE COMMODORE 1 28 OPERATING SYSTEM 4 1 9 



n 

n 



SECND is a low-level serial routine used to send a secondary address (SA) to 
a LISTNing device (see LISTN Kemal call). An SA is usually used to provide setup 
information to a device before the actual data I/O operation begins. Attention is 
released after a call to SECND. SECND is not used to send an SA to a TALKing 
device (see TKSA). (Most applications should use the higher level I/O routines: see 
OPEN and CKOUT). 



8. $FF96 TKSA ;serial: send SA after TALK 



n 

n 



n 



PREPARATION: 




Registers: 


.A = SA (secondary address) 


Memory: 


system map 


Hags: 


none 


Calls: 


TALK 


RESULTS: 




Registers: 


.A used 


Memory: 


STATUS ($90) 


Flags: 


none 


EXAMPLE: 




LDA#8 




JSR $FhB4 


;TALK device 8 


LDA #15 




JSR $FF93 


;pass it SA #15 



TKSA is a low-level serial routine used to send a secondary address (SA) to a 
device conunanded to TALK (see TALK Kemal call). An SA is usually used to 
provide setup information to a device before the actual data I/O operation 
begins. (Most applications should use the higher-level I/O routines; see OPEN and 
CHKIN). 



9. $FF99 MEMTOP ;set/read top of system RAM 



PREPARATION: 




Registers: 


.X = Isb of MEMSIZ 




.Y = msb of MEMSIZ 


Memory: 


system map 


Flags: 


.C = ^> set top of memory 




.C = 1 — > read top of memory 


Calls: 


none 
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RESULTS: 




Registers: 


.X = IsbofMEMSIZ 




.Y = msbofMEMSIZ 


Memory: 


MEMSIZ ($A07) 


Flags: 


none 


EXAMPLE: 




SEC 




JSR $FF99 


;get top of user RAMO 


DEY 




CLC 




JSR $FF99 


;lower it 1 block 



i 

u 



u 



o 



MEMTOP is used to read or set the top of system RAM, pointed to by 
MEMSIZ ($A07). This call is included in the CI 28 for completeness, but neither the 
Kemal nor BASIC utilizes MEMTOP since it has little meaning in the banked 
memory environment of the CI 28 (even the RS-232 buffers are permanently 
allocated). Nonetheless, set the carry status to load MEMSIZ into .X and .Y, and 
clear it to update the pointer from .X and .Y. Note that MEMSIZ references only 
system RAM (RAMO). The Kemal initially sets MEMSIZ to $FFOO (MMU and 
Kemal RAM code start here). 



10. $FF9C MEMBOT ;set/read bottom of system RAM 



u 
u 



PREPARATION: 




Registers: 


.X = IsbofMEMSTR 




.Y = msb of MEMSTR 


Memory: 


system map 


Hags: 


.C = -» set bot of memory 




.C = 1 -» read bot of memory 


Calls: 


none 


RESULTS: 




Registers: 


.X = IsbofMEMSTR 




.Y = msb of MEMSTR 


Memory: 


MEMSTR ($A05) 


Hags: 


none 


EXAMPLE: 





u 



u 



u 



SEC 

JSR $IT9C ;get bottom of user RAMO 

INY 

CLC 

JSR $RF9C ;raise it 1 block 



u 
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MEMBOT is used to read or set the bottom of system RAM, pointed to by 
MEMSTR ($A05). This call is included in the CI 28 for completeness, but neither 
the Kemal nor BASIC utilizes MEMBOT since it has little meaning in the banked 
memory environment of the C128. Nonetheless, set the carry status to load MEMSTR 
into .X and .Y, and clear it to update the pointer from .X and .Y. Note that 
MEMSTR references only system RAM (RAMO). The Kemal initially sets MEMSTR 
to $1000 (BASIC text starts here). 



11. $FF9F KEY ;scan keyboard 



PREPARATION: 




Registers: 


none 


Memory: 


system map 


Hags: 


none 


Calls: 


none 


RESULTS: 




Registers: 


none 


Memory: 


keyboard buffer 




keyboard flags 


Rags: 


none 


EXAMPLE: 




JSR $yy9F 


;scan the keyboard 



KEY is an Editor routine that scans the entire CI 28 keyboard (except the 
40/80 key). It distinguishes between ASCII keys, control keys, and program- 
mable keys, setting keyboard status bytes and managing the keyboard buffer. After 
decoding the key, KEY will manage such features as toggling cases, pauses or 
delays, and key repeats. It is normally called by the operating system during the 
60Hz IRQ processing. Upon conclusion, KEY leaves the keyboard hardware driv- 
ing the keyline on which the STOP key is located. 

There are two indirect RAM jumps encountered during a keyscan: KEYVEC 
($33A) and KEYCHK ($33C). KEYVEC (aUas KEYLOG) is taken whenever a key 
depression is discovered, before the key in .A has been decoded. KEYCHK is taken 
after the key has been decoded, just before putting it into the key buffer. KEYCHK 
carries the ASCII character in .A, the keycode in .Y, and the shiftkey status in .X. 

The keyboard decode matrices are addressed via indirect RAM vectors as 
well, located at DECODE ($33E). The following table describes them: 



$33E 


Mode 1 -» 


normal keys 


$340 


Mode 2 -» 


SHIFT keys 


$342 


Mode 3 -*■ 


C» keys 


$344 


Mode 4 -» 


CONTROL keys 


$346 


Mode 5 -^ 


CAPS LOCK keys 


$348 


Mode 6 -> 


ALT keys 
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The following list briefly describes some of the more vital variables utilized 
or maintained by KEY: 



u 



ROWS 


$DC01 


-^ 


I/O port outputting keys 


COLM 


$DCOO 


-* 


I/O port driving C64 keys 


VIC #47 


$D02F 


-*■ 


I/O port driving new keys 


8502 P6 


$0001 


-» 


I/O port sensing CAPS key 


NDX 


$D0 


-» 


keyboard buffer index 


KEYD 


$34A 


-* 


keyboard buffer 


XMAX 


$A20 


-*■ 


keyboard buffer size 


SHFLAG 


$D3 


-» 


shift key status 


RPTFLG 


$A22 


— > 


repeat key enables 


LOCKS 


$F7 


— > 


pause, mode disables 



KEY is also found in the Editor jump table as SCNKEY at $C012. 



12. $FFA2 SETTMO ;(reserved) 



u 



PREPARATION: 




Registers: 


none 


Memory: 


system map 


Flags: 


none 


Calls: 


none 


RESULTS: 




Registers: 


none 


Memory: 


TIMOUT ($AOE) 


Flags: 


none 


EXAMPLE: 




LDA #value 




JSR $FFA2 


;update TIMOUT 



SETTMO is not used in the CI 28 but is included for compatibility and 
completeness. It is used in the C64 by the IEEE communication cartridge to disable 
I/O timeouts. 



13. $FFA5 ACPTR ;serial:byte input 



u 



PREPARATION: 
Registers: 
Memory: 
Flags: 
CaUs: 



none 

system map 

none 

TALK 

TKSA (if necessary) 



n 
n 
n 



n 

n 

n 

n 
n 



n 
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RESULTS: 

Registers: 

Memory: 

Hags: 


.A = data byte 
STATUS ($90) 
none 


EXAMPLE: 




JSR SH^AS 
STA data 


;input a byte fro 



ACPTR is a low-level serial I/O utility to accept a single byte from the 
current serial bus TALKer using full handshaking. To prepare for this routine, 
a device must fu-st have been estabUshed as a TALKer (see TALK) and passed 
a secondary address if necessary (see TKSA). The byte is returned in .A. 
(Most applications should use the higher-level I/O routines; see BASIN and 
GETIN). 



14. SH^AS CIOUT ;serial: byte output 



PREPARATION: 




Registers: 


.A = data byte 


Memory: 


system map 


Hags: 


none 


Calls: 


LISTN 




SECND (if necessary) 


RESULTS: 




Registers: 


.A used 


Memory: 


STATUS ($90) 


Hags: 


none 


EXAMPLE: 




LDA data 




JSR $ITA8 


;send a byte via serial 



CIOUT is a low-level serial I/O utility to transmit a single byte to the current 
serial bus LISTNer using full handshaking. To prepare for this routine, a device 
must first have been established as a LISTNer (see LISTN) and passed a secondary 
address if necessary (see SECND). The byte is passed in .A. Serial output data is 
buffered by one character, with the last character being transmitted with EOI after a 
call to UNLSN. (Most applications should use the higher level I/O routines; see 
BSOUT.) 
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15. $FFAB UNTLK ;serial: send untalk 



PREPARATION: 
Registers: 
Memory: 
Flags: 
Calls: 

RESULTS: 
Registers: 
Memory: 
Hags: 

EXAMPLE: 

JSR $FFAB 



none 

system map 
none 
none 



.A used 
STATUS ($90) 
none 



;UNTALK serial device 



u 

u 



UNTLK is a low-level Kemal serial bus routine that sends an UNTALK 
command to all serial bus devices. It commands all TALKing devices to stop 
sending data. (Most applications should use the higher-level I/O routines; see 
CLRCH.) 



16. $FFAE UNLSN ;serial: send unlisten 



PREPARATION: 
Registers: 
Memory: 
Flags: 
CaUs: 

RESULTS: 
Registers: 
Memory: 
Flags: 

EXAMPLE: 

JSR $FFAE 



none 

system map 
none 
none 



.A used 
STATUS ($90) 
none 



;UNLISTEN serial device 



u 
u 



UNLSN is a low-level Kemal serial bus routine that sends an UNLISTEN 
command to all serial bus devices. It commands all LISTENing devices to stop 
reading data. (Most applications should use the higher-level I/O routines; see 
ICLRCH.) 



u 
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17. $FFB1 LISTN ;serial: send listen conunand 



n 

n 



PRiiPARATlOM: 
Registers: 


.A = device (0-31) 


Memory: 


system map 


Hags: 


none 


Calls: 


none 


RESULTS: 




Registers: 


.A used 


Memory: 


STATUS ($90) 


Hags: 


none 


EXAMPLE: 




JSR $FFB1 


;conunand device to 



n 



LISTN is a low-level Kemal serial bus routine that sends a LISTEN 
command to the serial bus device in .A. It commands the device to start read- 
ing data. (Most applications should use the higher-level I/O routines; see 
ICKOUT.) 



18. $FFB4 TALK ;serial: send talk 



n 



1 



PREPARATION: 




Registers: 


.A = device (0-31) 


Memory: 


system map 


Hags: 


none 


CaUs: 


none 


RESULTS: 




Registers: 


.A used 


Memory: 


STATUS ($90) 


Hags: 


none 


EXAMPLE: 




JSR $H'B4 


;command device to 



TALK is a low-level Kemal serial bus routine that sends a TALK command 
to the serial bus device in .A. It commands the device to start sending data. (Most 
applications should use the higher-level I/O routines; see ICHKIN.) 
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19. $FFB7 READSS ;read I/O status byte 



PREPARATION: 
Registers: 
Memory: 
Flags: 
CaUs: 

RESULTS: 
Registers: 
Memory: 
Flags: 

EXAMPLE: 

JSR $FFB7 



none 

system map 
none 
none 

.A = STATUS ($90 or $A14) 
STATUS cleared if RS-232 
none 



;STATUS for last I/O 



u 



u 



READSS (alias READST) returns the status byte associated with the last I/O 
operation (serial, cassette or RS-232) performed. Serial and cassette tape operations 
update STATUS ($90) and RS-232 I/O updates RSSTAT ($A14). Note that to 
simulate an ACIA, RSSTAT is cleared after it is read via READSS. The last I/O 
operation is determined by the contents of FA ($BA); thus applications that drive 
I/O devices using the lower-level Kemal calls should not use READSS. 



u 



20. $FFBA SETLFS ;set channel LA, FA, SA 



PREPARATION: 




Registers: 


.A = LA (logical #) 




.X = FA (device #) 




.Y = SA (secondary adr) 


Memory: 


system map 


Flags: 


none 


Calls: 


none 


RF„SULTS: 




Registers: 


none 


Memory: 


LA, FA, SA updated 


Flags: 


none 


EXAMPLE: 




See OPEN 





I 

u 



D 
D 



SETLFS sets the logical file number (LA, $B8), device number (FA, $BA) 
and secondary address (SA, $B9) for the higher-level Kemal I/O routines. The LA 
must be unique among OPENed files and is used to identify specific files for I/O 



U 



n 
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operations. The device number range is to 31 and is used to target I/O. The SA is 
a command to be sent to the indicated device, usually to place it in a particular 
mode. If the SA is not needed, the .Y register should pass $FF. SETLFS is often 
used along with SETNAM and SETBNK calls prior to OPENs. See the Kemal 
OPEN, LOAD and SAVE calls for examples. 



21. $FFBD SETNAM ;set filename pointers 



PREPARATION: 




Registers: 


.A = string length 




.X = string adr low 




.Y = string adr high 


Memory: 


system map 


Flags: 


none 


Calls: 


SETBNK 


RESULTS: 




Registers: 


none 


Memory: 


FNI.FN, FNADR updated 


Rags: 


none 


EXAMPLE: 




See OPEN 





n 



SETNAM sets up the filename or command string for higher-level Kemal I/O 
calls such as OPEN, LOAD and SAVE. The string (filename or command) length is 
passed in .A and updates FNLEN ($B7). The address of the string is passed in .X 
(low) and .Y (high). See the companion call, SETBNK, which specifies in which 
RAM bank the string is found. If there is no string, SETNAM should still be called 
and a null ($00) length specified (the address does not matter). SETNAM is often 
used along with SETBNK and SETLFS calls prior to OPENs. See the Kemal 
OPEN, LOAD and SAVE calls for examples. 



22. $FFCO OPEN ;open logical file 



PREPARATION: 




Registers: 


none 


Memory: 


system map 


Flags: 


none 


Calls: 


SETLFS, SETNAM, SETBNK 
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RESULTS: 




Registers: 


.A = error code (if any) 




.X used 




.Yused 


Memory: 


setup for I/O 




STATUS, RSSTAT updated 


Hags: 


.C = 1 -> error 


EXAMPLE: 


OPEN l,8,15,"IO" 


LDA #length 


;fnlen 


LDX #<filename 


;fnadr (command) 


LDY #>filename 




JSR $hFBD 


;SE'1NAM 


LDX #0 


;fnbank (RamO) 


JSR $FF68 


;SETBNK 


LDA #1 


;la 


LDX #8 


;fa 


LDY #15 


;sa 


JSR SbttiA 


;SETLFS 


JSR $FFCO 


;OPEN 


BCS error 




filename .BYTE '10' 




length = 2 





u 



u 



OPEN prepares a logical file for I/O operations. It creates a unique entry in 
the Kemal logical file tables LAT ($362), FAT ($36C) and SAT ($376) using its 
index LDTND ($98) and data supplied by the user via SETLFS. There can be up to 
ten logical files OPENed simultaneously. OPEN performs device-specific opening 
tasks for serial, cassette and RS-232 devices, including clearing the previous status and 
transmitting any given filename or command string supplied by the user via SETNAM 
and SETBNK. The I/O status is updated appropriately and can be read via READSS. 

The path to OPEN is through an indirect RAM vector at $31 A. Applications 
may therefore provide their own OPEN procedures or supplement the system's by 
redirecting this vector to their own routine. 



u 
u 

1 

L 



23. $FFC3 CLOSE ;close logical file 



PREPARATION: 




Registers: 


.A = LA (logical #) 


Memory: 


system map 


Flags: 


.C (see text below) 


Calls: 


none 



u 



I ! 

I i 
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I \ 



I I 



I ! 



n 



RRSULTS: 
Registers: 


.A = error code (if any) 




.X used 




.Y used 


Memory: 


logical tables updated 




STATUS, RSSTAT updated 


Flags: 


.C = 1 ^^ error 


EXAMPLE: 




LDA#1 


;la 


JSR $FFC3 


;CLOSE 


BCS error 


;(tape files only) 



CLOSE removes the logical file (LA) passed in .A fi-om the logical file tables 
and performs device-specific closing tasks. Keyboard, screen and any unOPENed 
files pass through. Cassette files opened for output are closed by writing the last 
buffer and (optionally) an EOT mark. RS-232 I/O devices are reset, losing any 
buffered data. Serial files are closed by transmitting a CLOSE command (if an SA 
was given when it was opened), sending any buffered character, and UNLSTNing 
the bus. 

There is a special provision incorporated into the CLOSE routine of systems 
featuring a BASIC DOS command. If the following conditions are all true, a full 
CLOSE is not performed; the table entry is removed but a CLOSE command is not 
transmitted to the device. This allows the disk command channel to be properly 
OPENed and CLOSEd without the disk operating system closing all files on its 
end: 



.c = 


1 


->• 


indicates special CLOSE 


FA> = 


= 8 


— » 


device is a disk 


SA = 


15 


— » 


command channel 



The path to CLOSE is through an indirect RAM vector at $31C. Applications 
may therefore provide their own CLOSE procedures or supplement the system's by 
redirecting this vector to their own routine. 



n 



24. $FFC6 CHKIN ;set input channel 



PREPARATION: 




Registers: 


.X = LA (logical #) 


Memory: 


system map 


Flags: 


none 


Calls: 


OPEN 
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RESULTS: 
Registers: 


.A = error code (if any) 




.X used 




.Y used 


Memory: 


LA, FA, SA, DFLTN 




STATUS, RSSTAT updated 


Flags: 


.C = 1 -» error 


EXAMPLE: 




LDX#1 


;ia 


JSR $FFC6 


;CHKIN 


BCS error 





CHKIN establishes an input channel to the device associated with the logical 
address (LA) passed in .X, in preparation for a call to BASESJ or GETIN. The 
Kemal variable DFLTN ($99) is updated to indicate the current input device and the 
variables LA, FA and SA are updated with the file's parameters from its entry in 
the logical file tables (put there by OPEN). CHKIN performs certain device specific 
tasks: screen and keyboard channels pass through, cassette files are confirmed for 
input, and serial channels are sent a TALK command and the SA transmitted (if 
necessary). Call CLRCH to restore normal I/O channels. 

CHKIN is required for all input except the keyboard. If keyboard input is 
desired and no other input channel is established, you do not need to call CHKIN or 
OPEN. The keyboard is the default input device for BASIN and GETIN. 

The path to CHKIN is through an indirect RAM vector at $3 IE. Applications 
may therefore provide their own CHKIN procedures or supplement the system's by 
redirecting tiiis vector to their own routine. 



U 







U 
U 



25. $FFC9 CKOUT ;set output channel 



PREPARATION: 
Registers: 


.X = LA (logical #) 


Memory: 


system map 


Flags: 


none 


Calls: 


OPEN 


RESULTS: 




Registers: 


.A = error code (if any) 




.X used 




.Y used 


Memory: 


LA, FA, SA, DFLTO 




STATUS, RSSTAT updated 


Flags: 


.C = 1 -» error 



u 



u 



n 



EXAMPLE: 
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I 1 



LDX#1 


;la 


JSR $FFC9 


;CKOUT 


BCS error 





I I 

I I 



n 



CKOUT establishes an output channel to the device associated with the 
logical address (LA) passed in .X, in preparation for a call to BSOUT. The Kemal 
variable DFLTO ($9A) is updated to indicate the current output device and the 
variables LA, FA and SA are updated with the file's parameters from its entry in 
die logical file tables (put there by OPEN). CKOUT performs certain device 
specific tasks: keyboard channels are illegal, screen channels pass through, cassette 
files are confirmed for output, and serial channels are sent a LISTN command and 
the SA transmitted (if necessary). Call CLRCH to restore normal I/O channels. 

CKOUT is required for all output except the screen. If screen output is 
desired and no other output channel is established, you do not need to call CKOUT 
or OPEN. The screen is the default output device for BSOUT. 

The path to CKOUT is through an indkect RAM vector at $320. Applications 
may therefore provide their own CKOUT procedures or supplement the system's by 
redirecting this vector to then: own routine. 



{ i 



26. $FFCC CLRCH ;restore default channels 



I ( 



! I 



PREPARATION: 




Registers: 


none 


Memory: 


system map 


Flags: 


none 


Calls: 


none 


RESULTS: 




Registers: 


.A used 




.X used 


Memory: 


DFLTI, DFLTO updated 


Flags: 


none 


EXAMPLE: 




JSR $FFCC 


;restore default I/O 



rn 



CLRCH (alias CLRCHN) is used to clear all open channels and restore the 
system default I/O channels after other channels have been established via CHKIN 
and/or CHKOUT. The keyboard is the default input device and the screen is the 
default output device. If the input channel was to a serial device, CLRCH first 
UNTLKs it. If the output channel was to a serial device, it is UNLSNed first. 
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The path to CLRCH is through an indurect RAM vector at $322. Applications 
may therefore provide their own CLRCH procedures or supplement the system's by 
redirecting this vector to their own routine. 



27. $FFCF BASIN ;input from channel 



PREPARATION: 




Registers: 


none 


Memory: 


system map 


Flags: 


none 


Calls: 


CHKDSf (if necessary) 


RESULTS: 




Registers: 


.A = character (or error code) 


Memory: 


STATUS, RSSTAT updated 


Flags: 


.C = 1 if error 


EXAMPLE: 




LDY#0 


;index 


MORE JSR $FFCF 


;input a character 


STA data.Y 


;buffer it 


INY 




CMP #$0D 


;carriage return? 


BNE MORE 





u 



y 



BASIN (alias CHRIN) reads a character from the current input device (DFLTN 
$99) and returns it in .A. Input from devices other than the keyboard (the default 
input device) must be OPENed and CHKINed. The character is read from the input j 

buffer associated with the current input channel: [ 

a. Cassette data is returned a character at a time from the cassette buffer at $B00, ^ 
with additional tape blocks being read when necessary. \ 

b. RS-232 data is retumed a character at a time from the RS-232 input buffer at $C(X), *" 
waiting until a character is received if necessary. If RSSTAT ($A14) is bad from 

a prior operation, input is skipped and null input (carriage return) is substituted. j 

c. Serial data is retumed a character at a time directly from the serial bus, waiting i 
until a character is sent if necessary. If STATUS ($90) is bad from a prior 
operation, input is skipped and null input (carriage return) is substituted. i 

d. Screen data is read from screen RAM starting at the current cursor position and I 
ending with a pseudo carriage return at the end of the logical screen line. The 

way the BASIN routine is written, the end of line (EOL) is not recog- 
nized. Users must therefore count characters themselves or otherwise detect ] 
when the logical EOL has been reached. 



L 



U 



n 



1 i 



I ( 



' i 
I i 
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II 
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' e. Keyboard data is input by turning on the cursor, reading characters from the 

keyboard buffer, and echoing them on the screen until a carriage return is 

rr encountered. Characters are then returned one at a time from the screen until 

i \ all characters input have been passed, including the carriage return. Any calls 

after the EOL will start the process over again. 



The path to BASIN is through an indirect RAM vector at $324. Applications 
may therefore provide then: own BASIN procedures or supplement the system's by 
redirecting this vector to their own routine. 



28. $FFD2 BSOUT ;output to channel 



PREPARATION: 




Registers: 


.A = character 


Memory: 


system map 


Flags: 


none 


Calls: 


CKOUT (if necessary) 


RESULTS: 




Registers: 


.A = error code (if any) 


Memory: 


STATUS, RSSTAT updated 


Flags: 


.C = 1 if error 


EXAMPLE: 




LDA #character 




JSR $FFD2 


;output a character 



BSOUT (alias CHROUT) writes the character in .A to the current output 
device (DFLTO $9 A). Output to devices other than the screen (the default output 
device) must be OPENed and CKOUTed. The character is written to the output 
buffer associated with the current output channel: 

a. Cassette data is put a character at a time into the cassette buffer at $B(X), with 
tape blocks being written when necessary. 

b. RS-232 data is put a character at a time into the RS-232 output buffer at $D00, 
waiting until there is room if necessary. 

c. Serial data is passed to CIOUT, which buffers one character and sends the 
previous character. 

d. Screen data is put into screen RAM at the current cursor position. 

e. Keyboard output is illegal. 

The path to BSOUT is through an indkect RAM vector at $326. Applications 
may therefore provide their own BSOUT procedures or supplement the system's by 
redirecting this vector to their own routine. 



n 
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29. $FFD5 LOAD ;load from file 



PREPARATION: 




Registers: 


.A = ^ LOAD 




.A > ^ VERIFY 




.X = loadadrlo(ifSA=0) 




.Y = loadadrhi(ifSA=0) 


Memory: 


system map 


Flags: 


none 


Calls: 


SETLFS, SETNAM, SEIBNK 


RESULTS: 




Registers: 


.A = error code (if any) 




.X = ending adr lo 




.Y = ending adr hi 


Memory: 


per command 




STATUS updated 


Rags: 


.C = 1 -» error 


EXAMPLE: 


LOAD "proeram",8,l 



LDA #length ;fnlen 
LDX #<filename ;fnadr 
LDY #>filename 
JSR $FFBD ;SETNAM 



LDA#0 
LDX#0 
JSR $FF68 

LDA#0 
LDX #8 
LDY #$FF 
JSR $FFBA 

LDA#0 

LDX #<load adr 
LDY #>load adr 
JSR $FFD5 
BCS error 
STX end lo 
STY end hi 



load/verify bank (RAM 0) 
fnbank (RAM 0) 
SETBNK 

la (not used) 

fa 

sa (SA>0 normal load) 

SETLFS 

load, not verify 
(used only if SA=0) 
(used only if SA=0) 
LOAD 



filename .BYTE 
length = 7 



program 



u 



This routine LOADs data from an input device into C128 memory. It can also 
be used to VERIFY that data in memory matches that in a file. LOAD performs 



u 



u 
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' ' device-specific tasks for serial and cassette LOADs. You cannot LOAD from 

RS-232 devices, tlie screen or the keyboard. While LOAD performs all the tasks of 

n an OPEN, it does not create any logical files as an OPEN does. Also note that LOAD 

I 1 cannot ' 'wrap' ' memory banks. As with any I/O, the I/O status is updated appropriately 

and can be read via READSS. LOAD has two options that the user must select: 



a. LOAD vs. VERIFY: The contents of .A passed at the call to LOAD deter- 
mines which mode is in effect. If .A is zero, a LOAD operation will be 
performed and memory will be overwritten. If .A is nonzero, a VERIFY 
operation will be performed and the result passed via the error mechanism. 

b. LOAD ADDRESS: the secondary address (SA) setup by the call to SETLFS 
determines where the LOAD starting address comes fi-om. If the SA is zero, 

r-* the user wants the address in .X and . Y at the time of the call to be used. If the 

j SA is nonzero, the LOAD starting address is read from the file header itself 

and the file is loaded into the same place from which it was SAVEd. 

T[ The C128 serial LOAD routine automatically attempts to BURST load a file, 

i I and resorts to the normal load mechanism (but still using the FAST serial routines) 

if the BURST handshake is not rehimed. 
r^ The path to LOAD is through an indirect RAM vector at $330. Applications 

may therefore provide their own LOAD procedures or supplement tiie system 

procedures by redirecting this vector to their own routine. 



I I 30. $FFD8 SAVE ;save to file 

^ PREPARATION: 

11 



Registers: 


.A = pointer to start adr 




.X = end adr lo 




.Y = end adr hi 


Memory: 


system map 


Flags: 


none 


Calls: 


SETLFS, SEINAM, SETBNK 


RESULTS: 




Registers: 


.A = error code (if any) 




.X = used 




.Y = used 


Memory: 


STATUS updated 


Flags: 


.C = 1 ^ error 


EXAMPLE: 


SAVE "program",8 


LDA #length 


;fnlen 


LDX #<filename 


;fnadr 


LDY #>filename 




JSR $FFBD 


jSETNAM 
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LDA#0 


;save from bank (RAM 0) 


LDX#0 


;fnbank (RAM 0) 


JSR $FF68 


;SETBNK 


LDA#0 


;la (not used) 


LDX#8 


;fa 


LDY#0 


;sa (cassette only) 


JSR $FFBA 


;SETLFS 


LDA #start 


•.pointer to start address 


LDX end 


;ending address lo 


LDYend+1 


;ending adr hi 


JSR $FFD8 


;SAVE 


BCS error 





filename .BYTE "program" 

length = 7 

start .WORD address 1 ;page-0 

end .WORD address2 

This routine SAVEs data from CI 28 memory to an output device. SAVE per- 
forms device-specific tasks for serial and cassette SAVEs. You cannot SAVE from 
RS-232 devices, the screen or the keyboard. While SAVE performs all the tasks of an 
OPEN, it does not create any logical files as an OPEN does. The starting address of 
the area to be SAVEd must be placed in a zero-page vector and the address of this 
vector passed to SAVE in .A at the time of the call. The address of the last byte 
to be SAVEd PLUS ONE is passed in .X and .Y at the same time. Cassette SAVEs 
utilize the secondary address (S A) to specify the type of tape header(s) to be generated: 

SA (bit 0) = ^ relocatable (blf) file 

= 1 -* absolute (plf) file 
SA (bit 1) = ^ normal end 

= 1 -» write EOT header at end 

There is no BURST save; the normal FAST serial routines are used. As with 
any VO, the I/O stattjs will be updated appropriately and can be read via READSS. 

The path to SAVE is through an indirect RAM vector at $332. Applications 
may therefore provide thek own SAVE procedures or supplement the system's by 
redirecting this vector to their own routine. 

31. $FFDB SETTIM ;set internal clock 



PARATION: 
Registers: 


.A = low byte 




.X = middle byte 




.Y = high byte 


Memory: 


system map 


Flags: 


none 


Calls: 


none 



u 

u 

u 



u 



u 
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I 1 



RESULTS: 




Registers: 


none 


Memory: 


TIME (SAO) updated 


Hags: 


none 


EXAMPLE: 




LDA#0 


;reset clock 


TAX 




TAY 




JSR $hFUB 


;SH1"1IM 



SETTIM sets the system software (jiffie) clock, which counts sixtieths (1/60) 
of a second. The timer is incremented during system IRQ processing (see UDTIM), 
and reset at the 24-hour point. SETTIM disables IRQ's, updates the three-byte timer 
with the contents of .A, .X and .Y, and re-enables IRQ's. 



32. $FFDE RDTIM ;read internal clock 



n 



n 



PREPARATION: 




Registers: 


none 


Memory: 


system map 


Flags: 


none 


Calls: 


none 


RESULTS: 




Registers: 


.A = low byte 




.X = middle byte 




.Y = high byte 


Memory: 


none 


Flags: 


none 


EXAMPLE: 




JSR $FFUE 


;RDTIM 



/ i 



RDTIM reads the system software (jiffie) clock, which counts sixtieths (1/60) 
of a second. The timer is incremented during system IRQ processing (see UDTIM), 
and reset at the 24-hour point. RDTIM disables IRQ's, loads .A, .X and . Y with the 
contents of the 3-byte timer, and re-enables IRQ's. 

33. $FFE1 STOP ;scan STOP key 



n 



PREPARATION: 




Registers: 


none 


Memory: 


system map 


Flags: 


none 


Calls: 


none 
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RFSULTS: 
Registers: 

Memory: 
Flags: 


.A = last keyboard row 
.X = used (if STOP key) 
none 
status valid 


EXAMPLE: 




JSR $FFE1 
BEQ stop 


;scan STOP key 
;branch if down 



STOP checks a Kemal variable STKEY ($91), which is updated by UDTIM 
during normal IRQ processing and contains the last scan of keyboard column C7. 
The STOP key is bit 7, which will be if the key is down. If it is, default I/O 
channels are restored via CLRCH and the keyboard queue is flushed by resetting 
NDX ($D0). The keys on keyboard line C7 are: 



1! 



vj 



) ( 



Bit: 


7 6 


5 


4 3 2 


1 


Key: 


STOP Q 


O 


SPACE 2 CTRL 


<- 1 



The path to STOP is through an indirect RAM vector at $328. Applications 
may therefore provide their own STOP procedures or supplement the system's by 
redirecting this vector to their own routine. 



'l1 



34. $FFE4 GETIN ;read buffered data 



PRFPARATION: 




Registers: 


none 


Memory: 


system map 


Flags: 


none 


Calls: 


CHKIN (if necessary) 


RESULTS: 




Registers: 


.A = character (or error code) 




.X used 




.Y used 


Memory: 


STATUS, RSSTAT updated 


Flags: 


.C = 1 if error 


EXAMPLE: 




wait JSR $FFE4 


;get any key 


BEQ wait 




STA character 





ii 



GETIN reads a character from the current input device (DFLTN ($99)) buffer 
and returns it in .A. Input from devices other than the keyboard (the default input 
device) must be OPENed and CHKINed. The character is read from the input buffer 
associated with the current input channel: 



11 



Ii 



u 
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a. Keyboard input: A character is removed from the keyboard buffer and passed 
in .A. If the buffer is empty, a null ($00) is returned. 

b. RS-232 input: A character is removed from the RS-232 input buffer at $C00 
and passed in .A. If the buffer is empty, a null ($00) is returned (use READSS 
to check validity). 

c. Serial input: GETIN automatically jumps to BASIN. See BASIN serial I/O. 

d. Cassette input: GETIN automatically jumps to BASIN. See BASIN cassette 
I/O. 

e. Screen input: GETIN automatically jumps to BASIN. See BASIN serial I/O. 

The path to GETIN is through an indirect RAM vector at $32A. Applications 
may therefore provide their own GETIN procedures or supplement the system's by 
redirecting this vector to their own routine. 



35. $FFE7 CLALL ;close all files and channels 



I \ 



PREPARATION: 




Registers: 
Memory: 
Rags: 
Calls: 


none 

system map 
none 
none 


RESULTS: 




Registers: 


.A used 
.X used 


Memory: 
Rags: 


LDTND, DFLTN, DFLTO updated 
none 


EXAMPLE: 




JSR $FFE7 


;close files 



i I 



CLALL deletes all logical file table entries by resetting the table index, 
LDTND ($98). It clears current serial channels (if any) and restores the default I/O 
channels via CLRCH. 

The path to CLALL is through an indirect RAM vector at $32C. Applications 
may therefore provide their own CLALL procedures or supplement the system's by 
redirecting this vector to their own routine. 



36. SFFEA UDTIM ;increment internal clock 



PREPARATION: 




Registers: 


none 


Memory: 


system map 


Rags: 


none 


Calls: 


none 
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RESULTS: 




Registers: 


.A used 




.X used 


Memory: 


TIME, TIMER, STKEY updated 


Flags: 


none 


EXAMPLE: 




SEI 




JSR $hhHA 


;UDTIM 


CLI 





UDTIM increments the system software (jiffie) clock, which counts sixtieths 
(1/60) of a second when called by the system 60Hz IRQ. TIME, a 3-byte counter 
located at $A0, is reset at the 24-hour point. UDTIM also decrements TIMER, also 
a 3-byte counter, located at $A1D (BASIC uses this for the SLEEP command, for 
example). You should be sure IRQ's are disabled before calling UDTIM to prevent 
system calls to UDTIM while you are modifying TIME and TIMER. 

UDTIM also scans key line C7, on which the STOP key lies, and stores the 
result in STKEY ($91). The Kemal routine STOP utilizes this variable. 

37. $FFED SCRORG ;get current screen window size 



PREPARATION: 




Registers: 


none 


Memory: 


system map 


Flags: 


none 


CaUs: 


none 


RESULTS: 




Registers: 


.A = screen width 




.X = window width 




.Y = window height 


Memory: 


none 


Flags: 


none 


EXAMPLE: 




JSR $hFHD 


;SCRORG 



SCRORG is an Editor routine that has been slightly changed from previous 
CBM systems. Instead of returning the maximum SCREEN dimensions in .X and 
.Y, the C128 SCRORG returns the current WINDOW dimensions. It does return 
the maximum SCREEN width in .A. These changes make it possible for applica- 
tions to "fit" themselves on the current screen window. SCRORG is also an Editor 
jump table entry ($CO0F). 





u 

li 
il 

I— ' 

1 ( 



'Li 



u 



u 






i I 



u 



U 
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38. $FFFO PLOT ;read/set cursor position 



! 1 
) i 



I I 



1 I 



; 1 



PREPARATION: 




Registers: 


.X = cursor line 




.Y = cursor column 


Memory: 
Rags: 


system map 

.C = -» set cursor position 


Calls: 


.C = 1 ^ get cursor position 
none 


RESULTS: 




Registers: 


.X = cursor line 




.Y = cursor column 


Memory: 
Hags: 


TBLX, PN TR updated 
.C = 1 -* error 


EXAMPLE: 




SEC 




JSR $FhFO 
INX 


;read current position 
;move down one line 


INY 
CLC 


;move right one space 


JSR $FFFO 
BCS error 


;set cursor position 

;new position outside window 



PLOT is an Editor routine that has been slightly changed from previous CBM 
systems. Instead of using absolute coordinates when referencing the cursor position, 
PLOT now uses relative coordinates, based upon the current screen window. The 
following local Editor variables are useful: 



1 SCBOT 


$E4 


-> 


window bottom 


SCTOP 


$E5 


— > 


window top 


SCLF 


$E6 


— > 


window left side 


s SCRT 


$E7 


-» 


window right side 


^ TBLX 


$EB 


-» 


cursor line 


PNTR 


$EC 


—> 


cursor column 


" LINES 


$ED 


— » 


maximum screen height 


1 COLUMNS 


$EE 


-* 


maximum screen width 



When called with the carry status set, PLOT returns the current cursor 
position relative to the current window origin (not screen origin). When called with 
the carry status clear, PLOT attempts to move the cursor to the indicated line and 
column relative to the current window origin (not screen origin). PLOT will return a 
clear carry status if the cursor was moved, and a set carry status if the requested 
position was outside the current window (no change has been made). 
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39. $FFF3 lOBASE ;read base address of I/O block 






PREPARATION: 

Registers: 


none 


Memory: 


system map 


Flags: 


none 


Calls: 


none 


RESULTS: 

Registers: 


.X = Isb of I/O block 




.Y = msb of I/O block 


Memory: 


none 


Flags: 


none 


EXAMPLE: 




JSR $FFF3 


;fmd the I/O block 



lOBASE is not used in the CI 28 but is included for compatibility and complete- 
ness. It returns the address of the I/O block in .X and .Y. 



ti 



li 



\ I 



NEW CI 28 KERNAL CALLS 



The following system calls are a set of extensions to the standard CBM jump table. 
They are specifically for the CI 28 and as such should not be considered as permanent 
additions to the standard jump table. With the exception of C64 MODE, they are all true 
subroutines and will terminate via an RTS. As with all Kemal calls, the system 
configuration (high ROM, RAM-0 and I/O) must be in context at the time of the 
call. 



U 



I. $FF47 SPIN SPOUT ;setup fast serial ports for I/O 



PREPARATION: 




Registers: 


none 


Memory: 


system map 


Hags: 


.C = ^ select SPINP 




.C = I ^ select SPOUT 


Calls: 


none 


RESULTS: 




Registers: 


.A used 


Memory: 


CIA-1, MMU 


Flags: 


none 



n 



i ! 



i! 
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I ' EXAMPLE: 

CLC 

I [ JSR $FF47 ;setup for fast serial input 

The CI 28/ 1571 fast serial protocol utilizes CIA 1 (6526 at $DCOO) and a 

rj special driver circuit controlled in part by the MMU (at $D500). SPINP and 

1 I SPOUT are routines used by the system to set up the CIA and fast serial driver 

circuit for input or output. SPINP sets up CRA (CIA 1 register 14) and clears the 

FSDIR bit (MMU register 5) for input. SPOUT sets up CRA, ICR (CIA 1 register 

13), timer A (CIA 1 registers 4 and 5), and sets the FSDIR bit for output. Note the 

state of the TODIN bit of CRA is always preserved, but the state of the GAME, 

EXROM and SENSE40 outputs of the MMU are not (reading these ports return the 

/ I state of the port and not the register values — consequently they cannot be pre- 

/ '■ served). These routines are required only by applications driving the fast serial bus 

themselves from the lowest level. 



1 1 
; \ 



2. $FF4A CLOSE ALL ;close all files on a device 



PREPARATION: 




Registers: 


.A ^ device # (FA: 0-31) 


Memory: 


system map 


Flags: 


none 


Calls: 


none 


RESULTS: 




Registers: 


.A used 




.Xused 




.Y used 


Memory: 


none 


Flags: 


none 


EXAMPLE: 




LDA #$08 




JSR $FF4A 


;close all files on device 8 



The FAT is searched for the given FA. A proper CLOSE is performed for all 
matches. If one of the CLOSEd channels is the current I/O channel, then the default 
channel is restored. 

This call is utilized, for example, by the BASIC conmiand DOLOSE. It is 
also called by the Kemal BOOT routine. 



n 
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3. $FF4D C64MODE ;reconfigure system as a C64 



PREPARATION: 




Registers: 


none 


Memory: 


system map 


Flags: 


none 


Calls: 


none 


RESULTS: 
Registers: 


none 


Memory: 


none 


Flags: 


none 


EXAMPLE: 




JMP $FF4D 


;switch to C 



There is no return from this routine. The 8502 DDR and port are initialized, 
and the VIC is set to IMHz (slow) mode. Control is passed to code in common 
(shared) RAM, which sets the MMU mode register (#5) to C64 mode. From this 
point on, the MMU and C128 ROMs are not accessible. The routine exits via an 
indirect jump through the C64 RESET vector. 

Since C64 operation does not allow for MMU access, all MMU registers must 
be configured for proper operation before the C64 mode bit is set. Similarly, 
because the start-up of the C64 operating system is not from a true hardware reset, 
there is the possibility that unusual I/O states in effect prior to C64MODE calls can 
cause unpredictable and presumably undesirable situations once in C64 mode. 

There is no way to switch from C64 mode back to C128 mode; only a 
hardware reset or power off/on will restore the CI 28 mode of operation. A reset 
will always initiate C128 mode, although altering the SYSTEM vector beforehand 
is one way to automatically "throw" a system back to C64 mode. 

4. $FF50 DMA CALL ;send command to DMA device 



PREPARATION: 




Registers: 


.X = bank (0-15) 




.Y = DMA controller command 


Memory: 


DMA registers set up system map 


Flags: 


none 


Calls: 


none 


RESULTS: 




Registers: 


.A used 




.X used 


Memory: 


changed as per command 


Flags: 


none 



u 
u 
n 



!! 



1! 



! / 



il 



) I 






) / 



LJ 



n 
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n 
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EXAMPLE: 

LDA #$00 
STA $DF02 
LDA #$20 
STA $DF03 

LDA #$00 
STA $DF04 
STA $DF05 
STA $DF06 

LDA #$40 
STA $DF07 
LDA #$1F 
STA $DF08 

LDX #$00 
LDY #$84 
JSR $FF50 



;setup CI 28 base address 
;low 

;high 

;setup expansion RAM address 

;low 

;high 

;bank (0-n, where n = 3 if 256K) 

;setup number of bytes 
;low 

;high 

;C128 bank 

;DMA command to "STASH" 

;execute DMA command 



n 



n 



n 



r i 

n 

n 



DMA CALL is designed to communicate with an external expansion car- 
tridge capable of DMA and mapped into system memory at 102 ($DFxx). The 
DMA CALL converts the logical CI 28 bank parameter to MMU configuration via 
GETCFG, OR's in the I/O enable bit, and transfers control to RAM code at $3F0. 
Here the CI 28 bank specified is brought into context, and the user's command is 
issued to the DMA controller. The actual DMA transfer is performed at this point, 
with the 8502 kept off the bus in a wait state. As soon as the DMA controller 
releases the processor, memory is reconfigured to the state it was in at the time of 
the call and control is returned to the caller. The user must analyze the completion 
status by reading the DMA status register at $DFOO. 

Care should be taken in the utilization of the CI 28 RAM expansion product 
by any application using the built-in Kemal interface. This includes especially the 
use of the C128 BASIC commands FETCH, STASH and SWAP. In the routine that 
prepares a DMA request for the user, the Kemal forces the I/O block to be always 
in context. Consequently, data from the DMA device is likely to corrupt sensitive 
I/O devices. Users should either bypass the Kemal DMA routine by providing 
their own interface, or limit the DMA data transfers to the areas above and below the 
I/O block. Only strict observance of the latter will guarantee proper utilization of 
the BASIC commands. The following code, used instead of the DMA CALL in the 
above example, illustrates a work-around: 

LDX #$00 ;C128 bank 

LDY #$84 ;DMA command to 'STASH' 

JSR $FF6B ;GETCFG 

TAX 

JSR $3F0 ;execute DMA command 
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5. $FF53 BOOT CALL ;boot load program from disk 



PREPARATION: 




Registers: 


.A = drive number (ASCII) 




.X = device number (0-31) 


Memory: 


system map 


Hags: 


none 


Calls: 


none 


RESULTS: 




Registers: 


.A used 




.Xused 




.Yused 


Memory: 


changed as per coimnand 


Flags: 


.C ^ 1 if I/O error 


EXAMPLE: 




LDA #$30 


;drive 


LDX #$08 


;device 8 


JSR $FF53 


;BOOT 


BCS 10 ERROR 




BCC NO BOOT SECTOR 



$00 $01 $02 $03 $04 $05 $06 ABC 

C B M adrl adrh bank blk# title file code 






BOOT attempts to load and execute the boot sector from an auto-boot disk in 
the given drive and device. The BOOT protocol is as follows: 

a. Close all open files on boot device. 

b. Read track 1 sector into TBUFFR ($B00). 

c. Check for auto-boot header, RTS if not. 

d. If (blk# > 0), BLOCK READ sequential sectors into RAM at given (adrl, 
adrh, bank) location. 

e. If LEN(filename) > 0, LOAD file into RAM-0 (normal load). 

f. JSR to user code at location C above. 

On any error, the BOOT operation is aborted and the UI command is issued "^ 
to the disk. A return may or may not be made to the caller depending upon the 

completion status and the BOOTed code. The BOOT sector has the following \ ' 

layout: l-i 



II 



I I 

u 

\ I 

u 

\ I 
i ) 
u 

U 

ii 



U 



where: A= $07-1- LEN(title) 

B= A -f- LEN(filename) I I 

C= B -h 1 U 



n 
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The following examples illustrate the flexibility of this layout. This loads and runs a 
BASIC program: 



$00 


— » 


CBM 


:key 


$03 


-» 


$00,$00,$00,$00 


:no other BOOT sector 


$07 


-^ 


NAME,$00 


message "NAME" 


$0C 


-> 


$00 


:no filename 


$0D 


-^ 


$A2,$13,$A0,$0B 

$4C,$A5,$AF 


xode 


$14 


-*■ 


RUN'TROGRAM" 


:data (BASIC stmt) 


$20 


-> 


$00 





I ! This results in the message Booting NAME... being displayed and, utilizing a 

C128 BASIC jump table entry that finds and executes a BASIC statement, loads 

and runs the BASIC program named "PROGRAM." The same header can be used 

n to load and execute a binary (machine code) program by simply changing RUN to 

' ' BOOT. (While the file auto-load feature of the boot header could be used to load 

binary files simply by furnishing a filename, to execute it you must know the 

P starting address and JMP to it. BASIC'S BOOT command does that, and allows a 

I ! more generic mechanism.) In the next example, a menu is displayed and you are 

asked to select the operating mode. Nothing else is loaded in this "configure"-type 

-^ header: 

I 
1 

$00 -^ CBM :key 

Pj $03 -^ $00,$00,$00,$00 :no other BOOT sector 

I 1 $07 -» $00 :no message 

$0C -» $00 :no filename 

n $0D ^ $20,$7D,$FF,$0D,$53,$45,$4C, $45 

\ I $43,$54,$20,$4D,$4F,$44,$45,$3A 

$OD,$OD, $20, $31, $2E, $20, $43, $36 
^ $34, $20, $20, $42, $41 , $53, $49, $43 

I i $0D, $20,$32,$2E,$20, $43,$31,$32 

$38, $20, $42, $41, $53, $49, $43,$0D 

$20, $33,$2E, $20, $43, $31, $32, $38 
P $20,$4D, $4F, $4E, $49, $54, $4F, $52 

$OD,$OD, $00, $20,$E4,$FF,$C9, $31 

$D0, $03,$4C,$4D,$FF,$C9, $32,$D0 
p $03,$4C, $03, $40,$C9, $33,$D0, $E3 

j $4C, $00,$B0 

P The loading of sequential sectors is designed primarily for specialized applications 

I I (such as CP/M or games) that do not need a disk directory entry. 
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6. $FF56 PHOENIX ;init function cartridges 



PREPARATION: 




Registers: 


none 


Memory: 


cartridge map 


Flags: 


none 


Calls: 


none 


RESULTS: 




Registers: 


.A used 




.X used 




.Y used 


Memory: 


changed as per command 


Flags: 


none 


EXAMPLE: 




JSR $FF56 


;PHOENIX 



The CI 28 Kemal initialization routine POLL creates a Physical Address 
Table (PAT) containing the ID's of all installed function ROM cartridges. PHOENIX 
calls each logged cartridge's cold-start entry in the order: external low/high, and 
internal low/high. After calling the cartridges (if any), PHOENIX calls the Kemal 
BOOT routine to look for an auto-boot disk in drive of device 8 (see BOOT CALL). 
Control may or may not be returned to the user. PHOENIX is called by BASIC at 
the conclusion of its cold initialization. 



u 



u 

1 i 



u 



u 



u 



7. $FF59 LKUPLA ;search tables for given LA 



8. $FF5C LKUPSA ;search tables for given SA 



PREPARATION: 




Registers: 


.A= LA (logical file number) 




if LKUPLA 




.Y= SA (secondary address) 




if LKUPSA 


Memory: 


system map 


Flags: 


none 


Calls: 


none 


RESULTS: 




Registers: 


.A = LA (only if found) 




.X = FA (only if found) 




.Y = SA (only if found) 


Memory: 


none 


Flags: 


.C = if found 



u 



u 

I j 
U 
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EXAMPLE: 

LDY #$60 ;find an available SA 
AGAIN INY 

CPY #$6F 

BCS TOO MANY ;too many files open 

JSR $FF5C ;LKUPSA 

BCC AGAIN ;get another if in use 

LKUPLA and LKUPSA are Kemal routines used primarily by BASIC DOS 
commands to work around a user's open disk channels, llie Kemal requires unique 
logical device numbers (LA's), and the disk requires unique secondary addresses 
(SA's); therefore BASIC must find alternative unused values whenever it needs to 
establish a disk channel. 



9. $FF5F SWAPPER ;switch between 40 and 80 columns 



PREPARATION: 




Registers: 


none 


Memory: 


system map 


Rags: 


none 


Calls: 


none 


RESULTS: 




Registers: 


.A used 




.X used 




.Y used 


Memory: 


local variables swapped 


Flags: 


none 


EXAMPLE: 




LDA $D7 


;check display mode 


BMI is 80 


;branch if 80-column 


JSR $FF5F 


;switch from 40 to 80 



SWAPPER is an Editor utility used to switch between the 40-column VIC 
(composite) video display and the 80-column 8563 (RGBI) video display. The 
routine simply swaps local (associated with a particular screen) variables, TAB 
tables and line wrap maps with those describing the other screen. The MSB of 
MODE, location $D7, is toggled by SWAPPER to indicate the current display 
mode: $80= 80-column, $00= 40-column. 
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10. $FF62 DLCHR ;init 80-col character RAM 



U 



PREPARATION: 
Registers: 


none 


Memory: 


system map 


Flags: 


none 


Calls: 


none 


RESULTS: 
Registers: 


.A used 




.X used 




.Y used 


Memory: 


8563 character RAM initialized 


Flags: 


none 


EXAMPLE: 




JSR $FF62 


;initialize 8563 char, defns. 



u 



DLCHR (alias INIT80) is an Editor utility to copy the VIC character 
definitions from ROM ($DOOO-$DFFF, bank 14) to 8563 display RAM ($2000- 
$3FFF, local to 8563-not in processor address space). The 8 by 8 VIC character 
cells are padded with nulls ($00) to fill out the 8 by 16 8563 character cells. 
Refer to Chapter 10, Programming the 80-Column (8563) Chip for details concerning 
the 8563 font layout. 



U 



U 



11. $FF65 PFKEY ;program a function key 



PREPARATION: 




Registers: 


.A = pointer to string adr 




(lo/hi/bank) 




.Y = string length 




.X = key number (1-10) 


Memory: 


system map 


Flags: 


none 


Calls: 


none 


RESULTS: 




Registers: 


.A used 




.X used 




.Y used 


Memory: 


PKYBUF, PKYDEF tables updated 


Flags: 


.C = if successful 




.C = 1 if no room available 



u 
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n 
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EXAMPLE: 



LDA #$FA 
LDY #$06 
LDX #$0A 
JSR $FF65 
BCS NO ROOM 



;pointer to string address 

;length 

;key # (HELP key) 

;install new key def n 



>OOOFA 00 13 00 :ptr to $1300 bank 

>01300 53 54 52 49 4E 47 :"string" 

PFKEY (alias KEYSET) is an Editor utility to replace a C128 function key 
string with a user's string. Keys 1-8 are F1-F8, 9 is the SHIFT RUN string, 
and 10 is the HELP string. The example above replaces the "help" RETURN 
string assigned at system initialization to the HELP key with the string ' 'string. ' ' 
Both the key length table, PKYBUF ($1000-$1009), and the definition area, 
PKYDEF ($100A-$10FF) are compressed and updated. The maximum length of all 
ten strings is 246 characters. No change is made if there is insufficient room for a 
new definition. 



12. $FF68 SETBNK ;set bank for I/O operations 



PREPARATION: 

Registers: 


.A = BA, memory bank (0-15) 




.X = FNBANK, filename bank 


Memory: 


system map 


Flags: 


none 


Calls: 


SETNAM 


RESULTS: 




Registers: 


none 


Memory: 


BA, FNBANK updated 


Flags: 


none 


EXAMPLE: 




See OPEN 





SETBNK is a prerequisite for any memory I/O operations, and must be used 
along with SETLFS and SETNAM prior to OPENing files, etc. BA ($C6) sets the 
current 64KB memory bank for LOAD/SAVE/VERIFY operations. FNBANK ($C7) 
indicates the bank in which the filename string is found. The Kemal routine 
GETCFG is used to translate the given logical bank numbers (0-15). SETBNK is 
often used along with SETNAM and SETLFS calls prior to OPEN's. See the Kemal 
OPEN, LOAD and SAVE calls for examples. 
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13. $FF6B GETCFG ;lookup MMU data for given bank 



u 
u 



PREPARATION: 
Registers: 
Memory: 
Flags: 
Calls: 

RESULTS: 
Registers: 
Memory: 
Flags: 

EXAMPLE: 

LDX #$00 
JSR $FF6B 
STA $FF01 



.X = logical bank # (0-15) 

system map 

none 

none 

.A = MMU configuration data 

none 

none 



logical bank (RAM 0) 

GETCFG 

setup MMU pre-config #1 



u 
u 



GETCFG allows a universal, logical approach to physical bank numbers by 
providing a simple lookup conversion for obtaining the actual MMU configuration 
data. In all cases where a bank number 0-15 is required, you can expect GETCFG 
to be called to convert that number accordingly. There is no error checking; if the 
given logical bank number is out of range the result is invalid. Refer to the Memory 
Management Unit in the Commodore 128 section later in this chapter for details concern- 
ing memory configuration. The C128 Kemal memory banks are assigned as follows: 



RAM only 

RAM 1 only 

RAM 2 only 

RAM 3 only 

INT ROM, RAM 0, I/O 

INT ROM, RAM 1,1/0 

INT ROM, RAM 2, I/O 

INT ROM, RAM 3, I/O 

EXT ROM, RAM 0, I/O 

EXT ROM, RAM 1,1/0 

EXT ROM, RAM 2, I/O 

EXT ROM, RAM 3, I/O 

KERNAL, INT LO, RAM 0, I/O 

KERNAL, EXT LO, RAM 0, I/O 

KERNAL, BASIC, RAM 0, CHAR ROM 

KERNAL, BASIC, RAM 0, I/O 



u 



0. 


%00111111 


1. 


%01111111 


2. 


%10111111 


3. 


%11111111 


4. 


%00010110 


5. 


%01010110 


6. 


%10010110 


7. 


%1 10101 10 


8. 


%00101010 


9. 


%01 101010 


10. 


%10101010 


11. 


%1 1101010 


12. 


%00000110 


13. 


%00001010 


14. 


%OG000001 


15. 


%00000000 
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14. $FF6E JSRFAR ;gosub in another bank 





15. $FF/1 JMPFAR ;goto 


another bank 


p 


PREPARATION: 




Registers: 


none 




Memory: 


system map, also: 


"■ 




$02 ^ bank (0-15) 




$03 ^ PC high 




$04 -^ PC low 






$05 -» .S (status) 


r 




$06 -^ .A 
$07 ^ .X 
$08 -^ .Y 


■- 


Flags: 


none 


Calls: 


none 




RESULTS: 




~ 


Registers: 


none 


Memory: 


as per call, also: 






$05 ^ .S (status) 


■ii^ 




$06 ^ .A 


1 

1 




$07 -* .X 


1 




$08 -^ .Y 




Flags: 


none 



n 



The two routines, JSRFAR and JMPFAR, enable code executing in the 
system bank of memory to call (or JMP to) a routine in any other bank. In the case 
of JSRFAR, a return will be made to the caller's bank. It should be noted that 
JSRFAR calls JMPFAR, which calls GETCFG. When calling a non-system bank, 
the user should take necessary precautions to ensure that interrupts (IRQ's and NMI's) 
will be handled properly (or disabled beforehand). Both JSRFAR and JMPFAR are 
RAM-based routines located in common (shared) RAM at $2CD and $2E3 
respectively. 

The following code illustrates how to call a subroutine in the second RAM 
bank from the system bank. Note that we need not worry about IRQ's and NMI's in 
this case because the system will handle them properly in any configuration that has 
the Kemal ROM or any valid RAM bank in context at the top page of memory. 



STY $08 
STX $07 
STA $06 
PHP 
PLA 
STA $05 



;assumes registers and status 
•.already setup for call 
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;want to call $2000 in bank 1 



LDA#1 
LDY #$20 
LDX #$00 
STA $02 
STY $03 
STX $04 

JSR $FF6E ;JSRFAR 

LDA $05 ;restore status and registers 

PHA 

LDA $06 

LDX $07 

LDY $08 

PLP 



u 



u 



16. $FF74 INDFET ;LDA (fetvec),Y from any bank 



PREPARATION: 




Registers: 


.A = pointer to address 




.X = bank (0-15) 




.Y = index 


Memory: 


setup indirect vector 


Flags: 


none 


CaUs: 


none 


RESULTS: 
Registers: 


.A = data 




.Xused 


Memory: 


none 


Flags: 


status valid 


EXAMPLE: 




LDA #$00 


;setup to read $2000 


STA $FA 




LDA #$20 




STA $FB 




LDA #$FA 




LDX #$01 


;in bank 1 


LDY #$00 




JSR $FF/4 


;LDA ($FA,RAM 1),Y 


BEQ etc 





u 



u 
u 



INDFET enables applications to read data from any other bank. It sets up 
FETVEC ($2AA), calls GETCFG to convert the bank number, and JMPs to code in 



u 



n 
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common (shared) RAM at $2A2 which switches banks, loads the data, restores the 
user's bank, and returns. When calling a non-system bank, the user should take 
necessary precautions to ensure that interrupts (IRQ's and NMI's) will be handled 
properly (or disabled beforehand). 



17. $FF77 INDSTA ;STA (stavec),Y to any bank 



n 



n 



1 1 



n 



PREPARATION: 




Registers: 


.A = data 




.X = bank (0-15) 




.Y = index 


Memory: 


setup indirect vector 




setup STAVEC ($2B9) pointer 


Flags: 


none 


Calls: 


none 


RESULTS: 




Registers: 


.X used 


Memory: 


changed per call 


Flags: 


status invalid 


EXAMPLE: 




LDA #$00 


;setup write to $2000 


STA $FA 




LDA #$20 




STA $FB 




LDA #$FA 




STA $2B9 




LDA data 




LDX #$01 


;in bank 1 


LDY #$00 




JSR $FF/7 


;STA ($FA,RAM 1),Y 



n 



n 



INDSTA enables applications to write data to any other bank. After you set 
up STAVEC ($239), it calls GETCFG to convert the bank number and JMPs to 
code in common (shared) RAM at $2AF which switches banks, stores the data, 
restores your bank, and returns. When calling a nonsystem bank, the user should 
take necessary precautions to ensure that interrupts (IRQ's and NMI's) will be 
handled properly (or disabled beforehand). 



n 
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18. $FF7A INDCMP ;CMP (cmpvec),Y to any bank 



PREPARATION: 




Registers: 


.A = data 




.X = bank (0-15) 




.Y = index 


Memory: 


setup indirect vector 




setup CMPVEC ($2C8) pointer 


Flags: 


none 


Calls: 


none 


RESULTS: 




Registers: 


.X used 


Memory: 


none 


Flags: 


status valid 


EXAMPLE: 




LDA #$00 


;setup to verify $2000 


STA $FA 




LDA #$20 




STA $FB 




LDA #$FA 




STA $2C3 




LDA data 




LDX #$01 


;in bank 1 


LDY #$00 




JSR $FF7A 


;CMP ($FA,RAM 1),Y 


BEQ same 





I 

u 
U 

y 



u 



CMPSTA enables applications to compare data to any other bank. After you 
set up CMPVEC ($2C8), it calls GETCFG to convert the bank number and JMP's to 
code in common (shared) RAM at $2BE which switches banks, compares the data, 
restores your bank, and returns. When calling a nonsystem bank, the user should 
take necessary precautions to ensure that interrupts (IRQ's and NMI's) will be 
handled properly (or disabled beforehand). 



19. $FF7D PRIMM ;print immediate utility 



PREPARATION: 




Registers: 


none 


Memory: 


none 


Flags: 


none 


Calls: 


none 



n 
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RESULTS: 

Registers: none 

Memory: none 

Flags: none 

EXAMPLE: 

JSR $FF7D ;display following text 

.BYTE "message" 

.BYTE $00 ;terminator 

JMP continue ;execution resumes here 

PRIMM is a Kemal utility used to print (to the default output device) an 
ASCII string which immediately follows the call. The string must be no longer than 
255 characters and is terminated by a null ($00) character. It cannot contain any 
embedded null characters. Because PRIMM uses the system stack to find the string 
and a return address, you must not JMP to PRIMM. There must be a valid address 
on the stack. 



CI28 DEVICE NUMBERS 



The following are the device numbers for the Commodore 128: 

-^ Keyboard 

1 -^ Cassette 

2 ^ RS-232 

3 -> Screen (current) 

4 — » Serial bus device: 

4-7 usually printers 
8-30 usually disks 

Device number 31 should not be used. While it is specified to be a valid serial bus 
address, when it is ORed with certain serial commands it results in a bad command, 
hanging the bus and the serial drivers. 
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MEMORY MANAGEMENT IN 
THE COMMODORE 128 

COMMODORE 128 MODE . 

lJ 

In Conunodore 128 mode, all memory management organization depends on the cur- 
rently selected memory configuration. In C128 BASIC and the Machine Language 
Monitor, the memory is organized into sixteen default memory configurations. Different I 

portions of memory are present depending on the memory configuration. Figure 13-3 >- 

lists the default memory configurations of the CI 28 on system power-up. 

Q 

BANK CONnGURATION 

RAM(O) only ] i 

1 RAM(l) only [J 

2 RAM(2) only (same as 0) 

3 RAM(3) only (same as 1) 

4 Internal ROM,RAM(0),I/O | j 

5 Internal ROM,RAM(l),I/0 U 

6 Internal R0M,RAM(2),I/0 (same as 4) 

7 Interaal ROM,RAM(3),I/0 (same as 5) ^ 

8 External ROM,RAM(0),I/O 

9 External ROM,RAM(l),I/0 U 

10 External R0M,RAM(2),I/0 (same as 8) 

11 External R0M,RAM(3),I/0 (same as 9) r , 

12 Kernal and Internal ROM (LOW), RAM(0),I/O | | 

13 Kernal and External ROM (LOW), RAM(0),I/O '~' 

14 Kernal and BASIC ROM, RAM (0), Character ROM 

15 Kernal and BASIC ROM, RAM(O), I/O 



Figure 13-3. Memory Configuration (Bank) table 

THE MEMORY MANAGEMENT 
UNIT (MMU) 



u 



In Commodore 128 mode, all memory management is controlled through a series of j 1 

I/O registers called the Memory Management Unit (MMU). The Memory Manage- [J 

ment Unit consists of memory locations that reside between $D5(X) and $D50B and 

$FFOO and $FF04. The configuration register appears twice, once at $D500 and again at 

$FFOO. This is done in case I/O is switched out of the $DO(K)-$DFFF memory range, 1 

which makes the MMU registers from $D500-$D50B inaccessible. L 

u 



n 
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When this occurs, some features of the MMU are no longer available to the 
programmer. So before switching out I/O in the $D00O-$DFFF range, make sure you 
have made all the manipulations you need on the MMU (particularly, preselecting the 
preconfiguration register values for the load configuration registers). See Figure 13-4 for 
a graphic depiction of the way the MMU registers map into memory. 



- LOAD CONFIGURflTION REG D 

- LORD CONFIGURflTION REG C 
LORD CGNFIGURRTIGN REG B 
LORD CONFIGURflTION REG fl 

^-CONFIGURflTION REGISTER 



VERSION REGISTER 
PRGE 1 POINTER HIGH 
PAGE 1 POINTER LOW 
PAGE POINTER HIGH 
PRGE POINTER LOW 
RRM CONFIGURflTION REGISTER 
MODE CONFIGURflTION REGISTER 
PRECONFIGURflTION REGISTER D 
PRECONFIGURflTION REGISTER C 
PRECONFIGURflTION REGISTER B 
PRECONFIGURflTION REGISTER fl 
CONFIGURflTION REGISTER 





/ 




/ 
-/- 

-/- 


$FFGLl 


LORD 


$FF03 


LCRC 


$FF02 


LCRB 


$FF01 


LCRfl 


$FF00 


CR 


/- 




/ 










/ 
-/- 
-/- 

/- 
/- 

/- 
/- 
/- 
/- 


$D50B 


VR 


$D50R 


PIH 


$0509 


PIL 


$0508 


PQH 


$0507 


PQL 


$0506 


RCR 


$0505 


MCR 


$D50U 


PCRO 


$0503 


PCRC 


$0502 


PCRB 


$0501—-- 


PCRfl 


$0500 


CR 


/- 



Figure 13-4. MMU Register Map 



HOW TO SWITCH BANKS 

In BASIC, type the BANK command to switch from one bank to another as follows: 

BANKn 

where n is a digit between and 15. When your application program needs to access a 
bank in which the microprocessor is not in context (for SYS, PEEK, POKE, and WAIT 
commands) use the BANK conmiand to reach layers of the computer's memory that are 
not accessible in the current bank. For instance, suppose you want to access the VIC 
chip when you are doing graphics in the first part of your program. The next segment 
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of your program needs to access the character ROM, which is only visible to the 8502 in 
bank 14. Change to bank 14; then read the character ROM data, which makes up the 
images of the characters in the character sets. While the microprocessor is "looking" in 
bank 14, the VIC chip is not available to the microprocessor, so you must issue another 
BANK command in order to return to (a configuration containing I/O and) processing 
VIC video information. 

In machine language, switching banks is a little more difHcult. You must change 
the value of the registers [in particular the Configuration Register (CR), Load Config- 
uration Register (LCR) and Preconfiguration Register (PCR)], either directly or 
indirectly. The Kemal routine GETCFG allows you to change configurations and 
maintains the same ones used by BASIC and the Monitor as they appear in Figure 13-3. 
There are four PCR's and four LCR's (as shown in Figure 13-4). Each PCR corresponds 
directly to a LCR. PCR A pertains to LCR A, PCR B corresponds to LCR B, and so on. 

To change the value of the Configuration Register directly, perform a write 
operation (STA, STX, STY) to the Configuration Register. 

To change the value of the Configuration Register indirectly, write a value 
specifying a memory configuration to the Preconfiguration Register. When a subsequent 
store instruction is performed to the corresponding Load Configuration Register, the 
value previously stored in the corresponding PCR is loaded into the CR. When a store 
instruction is executed on an LCR, the value in the corresponding PCR is loaded into the 
CR and the memory management organization conforms to the values associated with 
that memory management scheme. The value written to the LCR is of no consequence; 
any value triggers the preconfiguration mechanism. 



NOTE: Basic expects the LCR's and PCR's to be left alone. If you use 
them to manage memory in your application, do not plan on using BASIC. 



THE CONFIGURATION REGISTER 



U 
U 

u 



The Configuration Register (CR) is the most important register in the MMU. It specifies 
and organizes the ROM, RAM and input/output configurations for the entu-e Commo- 
dore 128 memory in C128 mode. (The MMU is not present at all in the C64 memory 
map.) The CR is located at address $D500 when I/O is available and at address $FFOO at 
all times. When I/O functions are disabled, the MMU memory disappears between 
$D500 and $D50B. The MMU memory is always present between $FFOO and $FF04. 
Each of the eight bits in the CR controls a separate memory function. 

Bit (zero) in the Configuration Register specifies whether I/O Registers are 
available, or whether ROM (High) is present in the memory range $D000 through 
$DFFF. The I/O Registers consist of the registers of the VIC chip, SID chip, MMU 
(from $D500 through $D50B); CIA number 1, which controls the joystick port; and CIA 
number 2, which controls the serial bus and user port. If bit is high (equal to 1), ROM 
or RAM is present in the range $D000 through $DFFF, depending upon the values of 
the ROM HIGH bits (4 and 5) in this register. If bit is low (equal to 0), I/O is present ] 

in this range. The value of bit on power-up is 0. •■ 







u 
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When I/O is switched out of (not present in) this range, the registers in the MMU 

^ disappear from the memory map in the range $D500 through $D50B. The memory manage- 

j j ment is then controlled through the MMU registers at locations $ITOO through $FF04. Any 

' ' write operation to an LCR ($FF01-$FF04) loads the corresponding PCR value (currently 

invisible to the 8502) into the CR. Reading an LCR returns the value stored in the 

/"[ currently inaccessible PCR. The MMU registers ranging fi-om $FFOO through $FF04 are 

/ ; always present in the Commodore 128 memory, regardless of the memory configuration. 

Bit 1 in the CR specifies how the microprocessor accesses the address range $4000 

r-s through $7FFF, called ROM LOW memory. If bit 1 is high, the microprocessor 

i I accesses RAM in this range. If bit 1 is low (equal to 0), the microprocessor maps in the 

BASIC LOW ROM in that range. Upon power-up or reset, this bit is set low, so 

BASIC is available to the user as soon as the computer is turned on. 

PI Bits 2 and 3 determine the type of memory that resides in the midrange of memory, 

! \ the address range $8000 through $BFFF. If both bits 2 and 3 are set high, RAM is 

placed in this range. If bit 2 is high and 3 is low, INTERNAL FUNCTION ROM is 

placed here. If bit 2 is low and 3 is high, EXTERNAL FUNCTION ROM appears. If 

bits 2 and 3 are low, the BASIC HIGH ROM is placed here. Upon power-up or reset, 

the MMU sets both bits 2 and 3 low, so BASIC is available to the user immediately. 

Bits 4 and 5 work similarly to bits 2 and 3 and specify memory in the range SCOOO 
through $FFFF, referred to as HIGH memory. If bits 4 and 5 are set high, RAM is 
placed in this range. If bit 4 is high and 5 is low, INTERNAL FUNCTION ROM is 
placed. If bit 4 is low and 5 is high, EXTERNAL FUNCTION ROM appears. If bits 4 
and 5 are low, the Kemal and character ROMs are placed here. Upon power-up or reset, 
bits 4 and 5 are set low, so the Kemal and character ROM are available to the user at once. 
Note that bit in the Configuration Register, the bit that switches in and out I/O in 
address range $D000 through $DFFF, overrides the memory organization for bits 4 and 5. 
If bit is set high (1), the I/O Registers are not in place in the address range $D000 
through $DFFF. Either the character ROM, internal or external function ROM or RAM 
is located in this range, depending on the value of bits 4 and 5 of the configuration 
register. If bit in the Configuration Register is set low (0), the Input/Output registers 
are present between $D000 through $DFFF, regardless of the value of bits 4 and 5 of the 
configuration register. This means no matter what memory configuration is chosen 
between $C000 and $FFFF with bits 4 and 5, if bit is set low (0), the character ROM 
(or whatever was originally in this address range) is overlaid by the yO registers and 
becomes unavailable to the microprocessor. This is why the character ROM and the I/O 
registers are never available at the same time. 

Finally, the last two bits of the MMU, 6 and 7, determine the RAM BANK 
selection. For the base system of 128K, only bit 6 is significant; bit 7 is not imple- 
mented. When bit 6 is high (1), RAM bank 1 is selected. When bit 6 is low (0), RAM 
bank is selected. 

The 128K of RAM is organized into two 64K RAM banks. The microprocessor 
only addresses 64K at a time, but since the two 64K RAM banks can be switched in and 
out so quickly, the computer acts as though it addresses 128K at the same time. When 
one RAM bank is being addressed by the microprocessor, the other bank stores 
information to be processed once it is banked in. Portions of both banks can be shared in 
memory at the same time. This is called Common RAM, and is discussed in the section 
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The RAM Configuration Register. RAM bank is used typically for BASIC text area, 
while RAM bank 1 is used for BASIC arrays and variable storage. 

As indicated above, the MMU has a feature that allows a portion of RAM to be 
common for the two RAM banks. The RAM Configuration Register controls the amount 
of common RAM. This is discussed in detail later in this section under the description of 
the RAM Configuration Register. 

Figure 13-5 is a diagram of the Configuration Register, showing how the bits 
control each memory organization. 



u 





Q 



BANK SELECT 


HI SPACE 

($COOO-$FFFF) 


MID-SPACE 

($8000-$BFFF) 


LO-SPACE 

($4000- 

$7FFF) 


I/O SPACE 
($D00O- 
$DIIF) 



00=RAM BANK 
01 = RAM BANK 1 
10= EXPANSION BANK 2 
II = EXPANSJ0NBANK3 



00 = KERNAL ROM 00 = BASIC ROM HI 

01 = INT. FUNCTION ROM 01 = INT. FUNCTION ROM 
IO=EXT. FUNCTION ROM 10 = EXT. FUNCTION ROM 
ll = RAM ll = RAM 



0= BASIC 0=I/O 
ROM LO REGISTERS 

I = RAM I=RAM/ROM 



Figure 13-5. Configuration Register 



u 



PRECONFIGURING COMMODORE 128 MEMORY 

As noted, the Configuration Register in the MMU is the means by which the Commo- 
dore 128 organizes the memory layout. Commodore 128 memory management has a 
mechanism that allows the programmer to set up four predefined memory configura- 
tions besides the one already operating. The four Preconfiguration Registers (PCR) 
and the four Load Configuration Registers (LCR) are designed to provide this feature. 
When a different memory management structure is desired, a previously defined 
configuration in one of the Preconfiguration Registers can be chosen easily and 
instantly. 

This mechanism allows the programmer to preset several memory configurations 
and, with a single store instruction to an LCR, reorganize the entire memory layout 
instantly. This enables the programmer to use several memory organizations inter- 
changeably; thus, if one part of your program requires one memory configuration and 
another part requires a different configuration, you can switch back and forth between 
the two, each with a single store instruction, once you predefine the alternate memory 
setup in one of the Preconfiguration Registers. 

To alter memory management through this preconfiguration mechanism, you 
must change the value of the Preconfiguration Register. The four PCR's and four 
LCR's of the MMU are shown in the MMU Register Map in Figure 13-6. Each 
PCR corresponds directly to an LCR (i.e., PCR A pertains to LCR A, PCR B 



u 



u 
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corresponds to LCR B, and so on). The format for the Load Configuration and 
Preconfiguration Registers is the same as for the Configuration Register. The four LCRs 
and four PCRs are all initialized to zero. 



/ 1 



1 \ 

r 

n 



; I 





/ 


/ 
/ 
/ 
/ 
/ 


$FFQii 


LCRO 


$FF03 


LCRC 


$FFQ2 


LCRB 


$FF01 


LCRfl 


$FF0O 


CR 


/ 










/ 


/ 
/ 
/ 
/ 

/ 
/ 

/ 
/ 
/ 
/ 


$D5QB 


VR 


$D5Qfi 


PIH 


$0509 


PIL 


$D508 


PQH 


$D507 


P0L 


$0506 


RCR 


$0505 


MCR 




$0504 


PCRO 


$0503 


PCRC 


$0502 


PCRB 


$0501 


PCRR 


$D500 


CR 


/ 



-, LOAD CONFIGURATION REG fl 
CGNFIGURflTION REGISTER 



^PRECONFIGURATION REGISTER fl 
CONFIGURATION REGISTER 



Figure 13-6. MMU Register Map 

To directly change the value of the Configuration Register (therefore bypassing 
the preconfiguration mechanism), perform a write operation (STA, STX, STY) directly 
to the Configuration Register at either $D500 or $FFOO. 

To indirectly change the value of the Configuration Register (therefore utilizing 
the preconfiguration mechanism), perform a write operation (STA, STX, STY) to the 
Preconfiguration Register. This loads a value into the PCR. When a subsequent store 
instruction is performed to the corresponding Load Configuration Register, the value 
that was previously stored in the corresponding PCR is loaded into the CR. The store 
instruction acts as a triggering mechanism that passes the contents of a PCR into the CR. 
When a store instruction is executed upon an LCR, the value in the corresponding PCR 
is loaded into the CR and memory management organization conforms to the value 
associated with diat PCR. 

For example, to alter the memory management organization specified on power-up, 
use the following machine language segment: 
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PART 1 LDA #$0E 



STA $D501 



Load accumulator with 14 

This selects 
I/O ($DOOO-$DFFF) 
RAM ($400a-$7FFF,$8000-$BFFF) 
Kemal and Character ROM ($COOO-$FFFF) 
RAM Bank 
Store in PCR A — no immediate results 



u 
u 



PART 2 STA$FF01 



Place interim part of the program here 
Write to LCR A, selects above configuration 



In this program segment, PART 1 initializes PCR A ($D50I) with the value 14 
($0E), which performs no immediate result. When PART 2 is encountered, the STA 
instruction performs a write operation to location $FF01 , which triggers the preconfiguration 
mechanism and loads the value from PCR A into the Configuration Register. The store 
instruction value is not significant; it must operate only on the address, and any store 
instruction works. Once this instruction is executed, the memory management organiza- 
tion is immediately changed according to the value in the appropriate PCR, in this case 
PCR A ($D501). 

The value 14 ($0E) loaded into PCR A selects the following memory organization: 







u 



TYPE 
I/O 

RAM 
RAM 

Kernal, Char 
RAM BANK 



ADDRESS RANGE BIT(S) AFFECTED IN CR 



$DOOO-$DFFF 
$4000-$7FFF 
$8000-$BFFF 
$COOO-$FFFF 




1 

2,3 
4,5 
6,7 



14 = $0E = 0000 1110 (binary) 



It is good practice to initialize the PCR's in the beginning of your program, as in 
PART 1 of the above program segment. Then place the interim portion of your program 
in memory. PART 2 marks the place in your program where you are actually going 
to alter the memory management setup. For the utmost speed and processor efficiency, 
use absolute addressing for the MMU registers, as in the above example. 

As previously noted, when the Input/Output Registers are switched out, the registers 
of the MMU that appear in memory range $D500-$D50B are unavailable to the micro- 
processor. When this occurs, a write operation to an LCR still loads the corresponding PCR 
value (currently invisible to the 8502) into the CR, even though the PCR's are not acces- 
sible to the microprocessor when I/O is switched out. If you switch out I/O, make sure to 
set up the PCR's first, which are present when bit of the Configuration Register is equal 
to 0. However, the Load Configuration Registers are available at all times since they 
appear in the address range $FF00-$FF04. If I/O is switched out, the PCR's must be 
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set prior to switching out I/O in order for them to be of any service. Note that BASIC uses 
the PCRs; if you alter them while BASIC is resident, you may obtain unpredictable results. 
The MMU registers control the memory organization for RAM, BASIC, Kemal 
and character ROM, internal and external function ROM, and I/O. The MMU has 
additional registers that determine the mode (C128, C64 or CP/M) in which the 
Commodore 128 operates, the conunon RAM configurations, and the location of pages 
and 1. The registers in the MMU that control these operations are the Mode 
Configuration Register (MCR), the RAM Configuration Register (RCR), and the 
Page Pointers respectively. The following sections explain how these additional regis- 
ters of the Memory Management Unit operate. 

THE MODE CONFIGURATION REGISTER 

The Mode Configuration Register (MCR) specifies which microprocessor is currently in 
operation (8502, Z80A) and which operating system mode is currently invoked (CI 28 or 
C64). The MCR is located at address $D505. As in the other registers in the MMU, 
each bit in the Mode Configuration Register controls a separate and independent 
operation. 

Bit determines which microprocessor is in control of the Commodore 128. Bit is 
powered-up low so the Z80 microprocessor initiates control of the computer. The Z80 
performs a small start-up procedure, then bit is set to a 1 and the 8502 takes over 
if no CP/M system disk is present in the disk drive. 

When the Commodore 128 is first powered-up or reset and the disk drive detects 
the CP/M operating system diskette in the drive, the Z80A microprocessor BOOTs the 
CP/M operating system from disk. The value of bit in the Mode Configuration 
Register in this case is 0. When the Z80A takes control of the Commodore 128, all 
memory references from $0000 through $OFFF are translated to $D000 through $DFFF, 
where the CP/M BIOS exists in ROM. For memory accesses in the range $0000 through 
$OFFF in the Z80 BIOS, the memory status lines MSO and MSI are brought low to 
reflect ROM; otherwise they are high. Note that C64 mode and Z80A mode is an 
undefined configuration. 

Bits 1 and 2 are not used. They are reserved for future expansion. IFO, bit 3 sets 
an input for FAST serial. It is not used as an input port at all. 

Bit 3 is the fast serial (FSDIR) disk drive control bit. It acts like a bit in a 
bidirectional 6529 port, which means it acts differently depending upon whether the bit 
is used for input or output operation. As an output signal, bit 3 controls the direction of 
the data in the disk drive data buffer. The MMU pin FSDIR reflects the status of bit 3, 
which is reset to zero upon power-up. If bit 3 is equal to 1 , an output operation occurs; 
selecting a data direction for the data in the serial bus buffer. If zero, bit 3 sets 
an input for FAST serial. It is not used as an input port at all. 

Bits 4 and 5 are the /GAME and /EXROM sense bits respectively. These cartridge 
control lines initiate Commodore 64 mode and act as the /GAME and /EXROM 
hardware lines as in the Commodore 64. When these control lines detect a cartridge in 
the Commodore 128 expansion port, C64 mode is instantly enabled, the computer acts 
as a Commodore 64 and takes its instructions from the software built into the cartridge. 
Upon power-up, /GAME and /EXROM are pulled as inputs. If either one is low, C64 
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mode is selected. Thus, a C128 cartridge should not pull these lines low on power-up. 
In C128 mode, these lines are active as I/O lines (latched) to the expansion port. These 
can be used as input or output lines, but make sure they are not brought low upon 
power-up in C128 mode. 

Bit 6 selects the operating system that takes over the Commodore 128. Upon 
power-up or reset, this bit is cleared (0) to enable all of the MMU registers and 
Commodore 128 mode features. Setting this bit high (1) initiates C64 mode. 

Bit 7, a read-only bit, indicates whether the 40/80 DISPLAY key is in 
the up (40-column) or down (80-column) position. The value of bit 7 is high (1) if 
the 40/80 key is in the up position. The value of bit 7 is low (0) if the 40/80 
D I SP LA Y key is in the down position. 

This is useful in certain application programs that utilize both the 40- and 
80-column displays. For instance, check the value of this bit to see if the user is viewing 
the VIC screen. If so, carry on with the program; otherwise display a message telling the 
user to switch from the 80-column screen to the VIC (40-column) screen in order to 
display a VIC bit map. This may be invalid if the user typed <ESC>X to switch 
screens. See the SCORG Kemal routine. 

See Figure 13-7 for a summary of Mode Configuration Register activities. 



u 



u 



$D505 



7 


6 


5 


4 


3 


2 


1 






Mode Configuration Register 



LI 



VALUE 



BFT FUNCTION DESCRIPTION 



HIGH 



/Select microprocessor 

Unused 

Unused 

Fast serial DD control 

/GAME Access game cartridge 

(C64 mode only) 

/EXROM Access external 

software cartridge (C64 mode 

only) 

Select operating system 



Read 40/80 
position 



key 



8502 



Fast serial out 



C64 mode 
(MMU disappears 
from memory map) 
40/80 column 
key is UP 



LOW 



Z80A (inverted) 



Fast serial in 
C(>4 mode set 
on power up 
C64 mode set 
on power up 

0128 mode, 
assert MMU 
registers 
40/80 column 
key is DOWN 



Figure 13-7. Mode Configuration Register Summary 
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THE RAM CONFIGURATION REGISTER 

The RAM Configuration Register (RCR) in the MMU specifies the amount of Common 
RAM shared between the two 64K RAM banks, how the RAM is shared, and which 
bank is delegated for the VIC chip. The value of the bits in the RCR determine how 
each RAM bank is allocated for specific purposes. The RAM Configuration Register is 
located within the I/O block at address $D506. 

Bits and 1 determine the amount of shared RAM between banks. If both bits 
and I equal 0, IK of RAM becomes common. If bit is equal to 1 (high) and bit 1 is 
low (0), then 4K of common RAM is shared between banks. If bit is low (0) and bit 1 
is high (1), then 8K is common, and if both bits 2 and 3 are high (1), then 16K of RAM 
becomes common. (These bits have no effect in Commodore 64 mode). The reset values 
of these bits are both 0. See Figure 13-8 to understand how the two RAM banks share 
common RAM. 
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Bits 2 and 3 specify which portions of the two RAM banks are common, if at all. If 
both bits are low (0), no RAM sharing occurs. If bit 2 is set high (1) and bit 3 is low (0), 
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a section of the bottom of RAM bank replaces the corresponding section of RAM bank 
1 for all RAM address accesses. If bit 3 is set high (1) and bit 2 is set low (0), a section 
of the top RAM bank replaces the corresponding section of RAM bank 1 for all RAM 
address accesses. If both bits 2 and 3 equal 1 (high), RAM is common to both the top 
and bottom of the RAM banks. Upon power-up or reset, bits 2 and 3 are set to 0, and no 
RAM is shared between banks. From a hardware standpoint, the 128K MMU selects the 
common RAM by forcing the CASO enable line low and CASl enable line high for all 
common memory accesses. 

Bits 4 and 5 have no assigned function. They are reserved for future expansion. 

Bits 6 and 7 in the RCR operate as a RAM bank pointer to tell the VIC chip which 
portion of RAM to use. At the present time, bit 7 is ignored. It too is reserved for 
future RAM expansion. When bit 6 is low (0) (driving CASO low), the VIC chip is told 
to look in RAM bank 0. When bit 6 is set high (1) (driving CASl low), the VIC chip is 
steered into RAM bank 1. Either setup allows the VIC chip RAM bank to be selected 
from the microprocessor RAM bank independently. 

When the microprocessor speed is increased to 2MHz, the VIC chip is disabled 
and the 80-column (8563) chip takes over the video processing. The VIC chip is 
affected by holding the AEC hardware line high. The disabling of the VIC chip is not 
directly affected by the actions of the MMU. 

Figure 13-9 summarizes the RAM Configuration Register activities. 



$D506 -* 

RAM Configuration Register 

BITS FUNCTIONAL DESCRIPTION 

I - Determine amount of shared RAM between RAM banks 

0= IK common RAM 
1= 4K common RAM 
10= 8K common RAM 

II = 16K common RAM 

3 2 - Determine wliich portions of RAM are sliared 

= No common RAM 

1 = Bottom of RAM bank is common 

10 = Top of RAM bank is common 

11 = Both top and bottom of RAM bank are common 

5 4- Not implemented; reserved for future expansion 

7 6 - Selects RAM bank for the VIC ciiip (Bit 7 is ignored) 

X = Select Bank for VIC chip 
X 1 = Select Bank 1 for VIC chip 

Note: X = not implemented 

Figure 13-9. RAM Configuration Register Summary 



7 6 5 4 3 2 10 



470 COMMODORE 128 



THE PAGE POINTERS 
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The Commodore 128 has a feature that allows you to relocate page ($00-$FF) and 

page 1 ($100-$1FF) of memory. Certain applications may require you to keep page 

intact while running BASIC, switch out the BASIC ROM, resume processing within the 

control of your machine language program, and then switch page and the BASIC 

ROM back in. Instead of transferring page with the machine language monitor, the 

page pointers make it easy to relocate pages and 1. Four registers within the MMU, 

called the page pointers, allow you to do this. The page pointers are located within the 

I/O block in the range $D507 through $D50A. The page pointers follow the standard | ) 

8502 low-byte/high-byte format. Here are the actual addresses of the high and low bytes 

of the page pointers: 

$D507 Page Pointer (low) i I 

$D508 Page Pointer (high) ^ 

$D509 Page 1 Pointer (low) 

$D50A Page 1 Pointer (high) i 

Bit of the high byte page pointers corresponds to the RAM bank number 
for any page address access. Bit controls the generation of the CASO hardware ; j 

control line if it is low and the CASl line if it is high, and bits 1 and 3 are |J 

ignored. 

To relocate page 0, perform a write operation on the high-byte page pointer. 
This is stored in the high-byte page pointer location and has no direct result until a write j 

operation is performed on the low-byte page pointer. When this occurs, bits through ^ 

7 of the low-byte page pointer correspond to the Translated Address lines TAB through 
TA15 for any page address reference, which relocates the page. Any subsequent 
page address is relayed to the new page zero. 

The page 1 pointer works the same way. Both pairs of pointers are initialized to 
upon power-up, placing pages and 1 in actual page and page 1 locations. 

It is important to note that memory addresses and 1 are always available at those 
absolute address references, regardless of whether pages zero or one are relocated. 

The page zero low-byte pointer directly replaces the high-order address of zero 
page (normally 00). When pages zero and one are directed to locations in RAM memory 
above page one, the MMU translates the addresses back to the normal locations of pages 
zero and one, effectively swapping those two pages of memory. This address translation 
applies only to RAM; ROM and I/O registers are not back-translated. VIC chip 
addresses are not translated back to their original memory locations, so you must ensure 
that you do not place page zero or one in the address of the VIC chip. The ROM 
appearing in these address ranges still overlays the RAM regardless of whether the RAM 
is zero page, page one or any other page of RAM memory. If you need to use the 
Kemal, the necessary variables required for the Kemal routine must be placed in 
memory where the Kemal is in context. Machine Language Monitor bank 15 ($0F) for 
example. 
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Bit of both high-byte page pointers (0 and 1) corresponds to the RAM bank 

number for any address access in page zero or one. The page zero high byte (bit 0) 

normally overrides the RAM bank set by the configuration register. However, if 

common RAM (at the bottom of RAM bank 0) is specified, the high-byte pointer for 

pages zero and one is ignored and pages zero and one appear in common RAM. Other- 

^^ wise, if common RAM is not allocated, pages zero and one appear where you specify 

( j according to the contents of the page pointers. In other words, common RAM takes priority 

' I over the page pointers, if common RAM is allocated by the RAM configuration register. 

This feature of relocatable page zero and page one provides many benefits to the 

p programmer. This allows machine language programs to create several pages of zero 

; } page variables or several different stacks. When you need to access the additional zero 

page variables or extra 256 bytes of the stack, simply change the pointer to look at the 

^ next page. This provides additional speed in your programs since you may use zero page 

I ; addressing for subsequent zero pages. You can even place zero page in screen memory 

r ; for extra fast writing to the screen. In addition, it gives you a way to implement deeper 

levels of subroutines since you have a larger stack area. Remember, though, to leave 

p-( three bytes on the top of the stack for interrupt requests and servicing. 



THE SYSTEM VERSION REGISTER 

The System Version Register, located in address $D50B, contains a value that tells the 
user which version of the MMU is inside the C128 and how large the memory is. Bits 
through 3 contain the MMU version number. Bits 4 through 7 contain a value (in 
memory blocks) pertaining to the size of the CI 28 memory. This allows the programmer 
to check the version of the C128 and the memory size, and make it compatible with 
systems that will be expanded in the future. The current version of the C128 contains the 
value $20, signifying two 64K blocks. 



AUTO STARTING A ROM 
APPLICATION CARTRIDGE 

Many of you may want to place your application program in a cartridge which plugs into 
the expansion port. In order to automatically start the program as soon as you turn on 
the computer, you must place a particular coded sequence in the first 6 bytes where the 
external (or internal) ROM cartridge maps into memory. Here's the auto start sequence 
in both CI 28 and C64 modes. 

COMMODORE 128 MODE 

Any C64 cartridge is asserted automatically if the system recognizes the /GAME or 
/EXROM as being pulled low. 

If any CI 28 cartridges are installed into the expansion port: 

1. Log the cartridge I.D. into the Physical Address Table (PAT). 

2. If the I.D. equals I, call the cold start vector (which may RTS). 
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The first 9 bytes of the Commodore 128 auto start sequence are: 



u 
u 



BYTE 
$X000 

$X003 
$X006 
$X007 
$X008 
$X009 



Cold Start Vector 

Warm Start Vector (not used but must be specified) 
Cartridge I.D. (The I.D. = 1 for an auto start card) 
The ASCn Character "C" with the high bit set 
The ASCn Character "B" with the high bit set 
The ASCn Character "M" with the high bit set 






where X is the hexadecimal digit "8" for $8000 or "C" for $C00O. 

There are four slots where cartridges (ROM's) may plug in (two internal, two 
external). They must follow the sequence described above, whether they are internal or 
external. 

COMMODORE 64 MODE 

The first 10 bytes of the Commodore 64 auto start sequence are: 



BYTE 

$X000 Cold start Vector 

$X003 Warm Start Vector 

$X006 The ASCH Character "C" with the high bit set 

$X007 The ASCn Character "B" with the high bit set 

$X008 The ASCII Character "M" with the high bit set 

$X009 The ASCn Character "8" with the high bit set 

$X0OA The ASCn Character "0" with the high bit set 
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where X is the hexadecimal digit "8" for $8000 or "C" for $C000. 

The recommended cartridge header for both operational modes is as follows: 

SEI 

JMP START 

NOP 

NOP 



This header is recommended so that the interrupt disable status bit is set when 
control is passed to the software in the cartridge ROM. 
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THE COMMODORE 128 
SCREEN EDITOR 
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The Commodore screen editor is among the easiest to use of all screen editors. As soon 
as you turn on the computer, the screen editor is available to you. You don't have to call 
any additional text editors. Using the keys for manipulating text, the screen editor gives 
you more freedom than most other editors. 

CI 28 EDITOR ESCAPE CODES 

To use the following ESCAPE functions, press the ESCAPE key and then press 
the key for the function you want. 



KEY FUNCTION 



A Enable auto-insert mode 

B Set bottom right of screen window at cursor position 

' ' C Disable auto-insert mode 

D Delete current line 

p E Set cursor to nonflashing mode 

I I F Set cursor to flashing mode 

G Enable bell (control-G) 

H Disable bell 

n I Insert line 

' ' J Move to start of current luie 

K Move to end of current line 

p L Enable scrolling 

' { M Disable scrolling 

N Return screen to normal (nonreverse video) state (80-column screen only) 

O Cancel insert, quote, underline, flash and reverse modes 

j ) P Erase to start of current line 

' ^ Q Erase to end of current Inie 

R Set screen to reverse video (80-column screen only) 

i—i) S Change to block cursor (80-column screen only) 

M T Set top left of screen window at cursor position 

U Change to underline cursor (80-column screen only) 

V Scroll up 
Pj W ScroH down 

/ I X Swap 40/80-coIumn display output device 

Y Set default tab stops (8 spaces) 
j»i Z Clear all tab stops 

I : @ Clear to end of screen 
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CI 28 EDITOR CONTROL CODES 

The following control characters in the CBM ASCII table have been added or changed 
from those found in the C64. Codes not shown in this table have the same function as 
found in the C64. 






u 



u 



CHR$ KEYBOARD 

VALUE CONTROL CHARACTER FUNCTION 



Underline ON (80-column screen only) 

Produces bell tone 

Tab character 

Line feed character 

Disable shift Commodore key (formerly code 9) 

Enable shift Commodore key (formerly code 8) 

Turn ON flash on (80-column screen only) 

Tab set/clear 

E^ape character 

Underline OFF (80-column screen only) 

Turn flash OFF (80-column screen only) 



CI 28 EDITOR JUMP TABLE 

The editor calls listed below are a set of extensions to the standard CBM jump table. 
They are specifically for the CI 28 and should not be considered as permanent additions 
to the standard jump table. They are all true subroutines and terminate with the RTS 
instruction. As with all Kemal calls, the system configuration (high ROM, RAM-0 and 
I/O) must be in context at the time of the call. 
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1. 


$C000 


CINT 


2. 


$C003 


DISPLY 


3. 


$C00(> 


LP2 


4. 


$C009 


LOOPS 


5. 


$C00C 


PRINT 


6. 


$C00F 


SCRORG 


7. 


$C012 


SCNKEY 


8. 


$C015 


REPEAT 


9. 


$C018 


PLOT 


10. 


$C018 


CURSOR 


11. 


$C01E 


ESCAPE 


12. 


$C021 


KEYSET 


13. 


$C024 


IRQ 


14. 


$C027 


INIT80 


15. 


$C02A 


SWAPPER 


16. 


$C02D 


WINDOW 


17. 


$C033 


LDTB2 


18. 


$C04C 


LDTBl 


19. 


$334 


CONTRL 


20. 


$336 


SHIFTD 


21. 


$338 


ESCAPE 


22. 


$33A 


KEYVEC 


23. 


$33C 


KEYCHK 


24. 


$33E 


DECODE 



initialize editor and screen 
:disp!ay .A=char, .X = color 
get a l(ey from irq buffer in .A 
get a clir from screen line in .A 
print cliaracter in .A 
:get size of current window 
scan Iceyboard subroutine 
repeat iiey logic and CKIT2 
read or set cursor position 
move 8563 cursor subroutine 
:execute escape function 
xedefine a programmable I(ey 
irq entry 

initialize 80-column char set 
;40/80 mode change 
:set UL or BR of window 
screen lines low byte table 
screen lines high byte table 
print CTRL indirect 
print S H F T indirect 
print ESC indirect 
:keyscan logic indirect 
keyscan store indirect 
keyboard decode table vectors 



Entries 17, 18, and 24 are table pointers, and are not callable routines. Entries 19-23 
are considered indirect vectors, not true entry points. 

This chapter has presented the Commodore 128 operating system. Chapter 16 
provides information on CP/M on the Commodore 128 and Commodore 64 memory 
maps. 
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CP/M® is a microprocessor operating system produced by Digital Research, Inc. (DRI). 
The version of CP/M used on the Commodore 128 is CP/M Plus® Version 3.0. In this 
chapter, CP/M is generally referred to as CP/M 3.0, or simply CP/M. 

This chapter summarizes the non-C128-dependent aspects of CP/M on the Commodore 
128. For detailed information on C128-dependent CP/M 3.0, see Appendix K of this 
guide. For detailed information on non-C128-dependent CP/M 3.0, see the Commodore- 
produced volume that includes DRI's CPIM Plus User's Guide, Programmer's Guide, 
and System Guide. 



REQUIREMENTS FOR A CP/M 3.0 SYSTEM 
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The general requirements for CP/M 3.0 are: 

■ A computer containing a Z80 microprocessor. 

■ A console consisting of a keyboard and a display screen. 

■ At least one floppy disk drive. 

■ CP/M system software on disk. 

CP/M 3.0 on the Commodore 128 Personal Computer normally consists of the 
following elements: 

■ A built-in Z80 microprocessor. 

■ A console consisting of the full Commodore 128 keyboard and an 80-column 
monitor. 

■ The Commodore 1571 fast disk drive. 

■ The CP/M system disk, which includes the CP/M 3.0 system, an extensive 
HELP utility program and a number of other utility programs. 
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NOTE: CP/M can also be used with a 40-column monitor. To view all 
80 columns of display, you must scroll the screen horizontally by press- 
ing the CONTROL key and the appropriate CURSOR key 
(left or right). 
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CP/M 3.0 can also be used with the 1541 disk drive. In this case, only single- 
sided GCR disks can be used, and the speed of operation will be approximately 
one-tenth the speed achieved using the 1571 disk drive. (See the discussion of disk 
formats later in this chapter for more details.) 
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COMMODORE ENHANCEMENTS 
n TO CP/M 3.0 

Commodore has added a number of enhancements to CP/M 3.0. These enhancements 
n tailor the capabilities of the Commodore 128 to those of CP/M 3.0. They include such 

I I things as a selectively displayed disk status line, a virtual disk drive, local/remote 

handling of keyboard codes, programmable function keys (strings) and a number of 
p-\ additional functions/characters that are assigned to various keys. These enhancements 

I are described at appropriate points in this chapter. 



CP/M FILES 



There are two types of CP/M files: 

■ PROGRAM or COMMAND files, consisting of a series of instructions that 
the computer follows to achieve a specified result. 

■ DATA files, consisting usually of a collection of related information (e.g., a 
list of customer names and addresses; inventory records; accounting records; the 
text of a document). 

FILE SPECIFICATION 

A CP/M file is identified by a file specification that can consist of up to four individual 
elements, as follows: 

■ Drive Specifier (optional), consisting of a single letter, followed by a colon. 
Each disk drive is assigned a letter, in the range A through E. (E denotes a 
virtual drive, as explained later in this chapter.) 

■ Filename (mandatory), which can be from one to eight characters long. (Note 
that this is the only mandatory element of the file specification.) 

■ Filetype (optional), consisting of one to three characters. It must be separated 
from the filename by a period. 

■ Password (optional), which can be from one to eight characters. Must be 
separated from the filetype (or filename, if no filetype is included) by a 
semicolon. 

EXAMPLE: 

The following file specification contains all four possible elements, all separated by the 
appropriate symbols: 

A:DOCUMENT.LAW;nREBIRD 
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USER NUMBER 

CP/M 3.0 further identifies ail files by assigning each one a user number, which can 
range from to 15. CP/M 3.0 assigns the user number to a file when the file is created. 
User numbers allow you to separate your files into sixteen file groups. 

Any user number other than must precede the drive specifier. User 0, which is 
the default user number, is not displayed in the prompt. 

If a file resides in user and is marked with a system file attribute, that file can 
be accessed from any user number. Otherwise, a command can access only those files 
that have the current user number. 

CREATING A FILE 

There are several ways to create a CP/M file, including: 

■ Using the CP/M text editor (ED). 

■ Using the PIP command to copy and rename a file. 

■ Using a program such as MAC (a CP/M machine language assembler program), 
which creates output files as it processes input files. 

USING WILDCARD CHARACTERS TO 
ACCESS MORE THAN ONE FILE 

A wildcard is a character that can be used in a filename or filetype in place of some other 
characters. CP/M 3.0 uses the question mark (?) and asterisk (*) as wildcards. A ? stands 
for any character that may be encountered in that position. An * tells CP/M to fill the 
filename with question mark characters as indicated. A file specification containing a wild- 
card can refer to more than one file and is therefore called an ambiguous file specification. 

RESERVED CHARACTERS 

The characters in Table 14-1 are reserved characters in CP/M 3.0. Use only as indicated. 

CHARACTER MEANING 

<$,!!>[] ] 

TAB, SPACE, } File specification delimiters 

CARRIAGE RETURN 
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Drive delimiter in file specification 

Filetype delimiter in file specification 

Password delimiter in file specification 

Comment delimiter at the beginning of a conmiand line 
* ? WUdcard characters in an ambiguous file specification 

< > & ! I \ + - Option list delimiters . 

[ ] Option list delimiters for global and local options j 

( ) Delimiters for multiple modifiers inside square L^ 

brackets for options that have modifiers 
/ $ Option delimiters in a command line 

Table 14-1. CP/M 3.0 Reserved Characters L 
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RESERVED FILETYPES 

The filetypes defined in Table 14-2 are reserved for system use. 

FILETYPE MEANING 

ASM Assembler source file 

BAS BASIC source program 

COM Z80 or equivalent machine language program 

HEX Output file from MAC (used by HEXCOM) 

HLP HELP message file 

$$$ Temporary file 

PRN Print file from MAC or RMAC 

REL Output file from RMAC (used by LINK) 

SUB List of commands to be executed by SUBMIT 

SYM Symbol file from MAC, RMAC or LINK 

SYS System file 

RSX Resident System Extension (a file automatically loaded by a command 
file when needed) 

Table 14-2. CP/M 3.0 Reserved Filetypes 

CP/M COMMANDS 

There are two types of commands in CP/M 3.0: 

■ Built-in commands, which identify programs in memory. 

■ Transient utility commands, which identify program files. 

CP/M 3.0 has six built-in commands and over twenty transient utility commands. 
Utilities can be added by purchasing CP/M 3.0-compatible application programs. In 
addition, experienced programmers can write utilities that operate with CP/M 3.0. 

BUILT-IN COMMANDS 

Built-in commands are entered in the computer's memory when CP/M 3.0 is loaded, 
and are always available for use, regardless of which disk is in which drive. Table 14-3 
lists the Commodore 128 CP/M 3.0 built-in commands. 

Some built-in commands have options that require support from a related transient 
utility. The related transient utility command has the same name as the built-in com- 
mand and has a filetype of COM. 
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COMMAND FUNCTION 



DIR 

DIRSYS 

ERASE 



Displays fllenames of all files in the directory except those marked with 
the SYS attribute. 



Displays filenames of files marked with the SYS (system) attribute in the 
directory. 

Erases a filename from the disk directory and releases the storage space 
occupied by the file. 

RENAME Renames a disk file. 

TYPE Displays contents of an ASCII (TEXT) fde at your screen. 

USER Changes to a different user number. 

Table 14-3. Built-in Commands 

TRANSIENT UTILITY COMMANDS 

The CP/M 3.0 transient utility commands are listed in Table 14-4. When a command key- 
word identifying a transient utility is entered, CP/M 3.0 loads the program file from the 
disk and passes that file any filenames, data or parameters specified in the command tail. 



u 

I 
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USING CONTROL CHARACTERS 
FOR LINE EDITING 

Table 14-5 lists the line-editing control characters for CP/M 3.0 on the Commodore 128. 

HOW TO MAKE COPIES OF 
CP/M 3.0 DISKS AND FILES 



u 



NOTE: The Digital Research Inc. COPYSYS command, used in many 
CP/M systems in formatting a disk, is not implemented on the Commo- 
dore 128 computer. Instead, the Commodore 128 uses a special FORMAT 
command. 



To make backups of the CP/M system disks, use the FORMAT and PIP utility 
programs. FORMAT formats the disk as either a C128 single-sided or C128 double-sided 
diskette. 
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NAME 



FUNCTION 



DATE Sets or displays the date and time. 

DEVICE Assigns logical CP/M devices to one or more physical devices, changes 
device driver protocol and baud rates, or sets console screen size. 

DIR Displays directory vrith flies and their characteristics. 

DUMP Displays a file in ASCII and hexadecimal format. 

ED Creates and alters ASCII files. 

ERASE Used for wildcard erase. 

GENCOM Creates a special COM file with attached RSX file. 

GET Temporarily gets console input from a disk file rather than the 
keyboard. 

FORMAT Initializes disk in GCR format for CP/M use. 

HELP Displays information on how to use CP/M 3.0 commands. 

INITDIR Initializes a disk directory to allow time and date stamping. 

KEYFIG Allows redefinition of keys. 

PATCH Displays or installs patches to CP/M system. 

PIP Copies files and combines files. 

PUT Temporarily directs printer or console output to a disk file. 

RENAME Changes the name of a file, or a group of files, using wildcard characters. 

SAVE Saves a program in memory to disk. 

SET Sets file options including disk labels, file attributes, type of time and 
date stamping and password protection. 

SETDEF Sets system options including the drive search cham. 

SHOW Displays disk and drive statistics. 

SUBMIT Automatically executes multiple commands. 

TYPE Displays contents of text file (or group of files, if wildcard characters are 
used) on screen (and printer if desired). 



Table 14-4. Transient Utility Commands 
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CHARACTER 



MEANING 



CTRL-A or 
SHIFT-LEFT CURSOR 

CTRL-B 



CTRL-E 



CTRL-F or 
RIGHT CURSOR 



CTRL-G 



CTRL-H 



CTRL-I 



CTRL-J 



CTRL-K 
CTRL-M 



CTRL-R 



CTRL-U 



CTRL-Wor fCRSRi 



CTRL-X 



Moves the cursor one character to the left. 

Moves the cursor to the beguuihig of the conunand Une without 
having any effect on the contents of the line. If the cursor is 
at the beginning, CTRL-B moves it to the end of the line. 

Forces a physical carriage return but does not send the 
command line to CP/M 3.0. Moves the cursor to the begin- 
ning of the next line without erasing the previous input. 

Moves the cursor one character to the right. 

Deletes the character at current cursor position. The cursor 
does not move. Characters to the right of the cursor shift 
left one place. 

Deletes the character to the left of the cursor and moves 
the cursor left one character position. Characters to the right 
of the cursor shift left one place. 

Moves the cursor to the next tab stop. Tab stops are auto- 
matically set at each eighth column. Has the same effect 
as pressing the TAB key. 

Sends the command line to CP/M 3.0 and returns the cursor 
to the beginning of a new line. Has the same effect as a 
RETURN or a CTRL-M keystroke. 

Deletes to the end of the line from the cursor. 

Sends the command line to CP/M 3.0 and returns the cursor 
to the beginning of a new line. Has the same effect as a 
RETURN or a CTRL-J keystroke. 

Retypes the command line. Places a # character at the 
current cursor location, moves the cursor to the next line, 
and retypes any partial command you typed so far. 

Discards all the characters in the command line, places a 
# character at the current cursor position, and moves the 
cursor to the next line. However, you can use a CTRL-W to 
recall any characters that were to the left of the cursor 
when you pressed CTRL-U. 

Recalls and displays previously entered command line both 
at the operating system level and within executing programs, 
if the CTRL-W is the first character entered after the 
prompt. CTRL-J, CTRL-M, CTRL-U and RETURN define 
the command line you can recall. If the command line 
contains characters, CTRL-W moves the cursor to the end 
of the command line. If you press RETURN , CP/M 
3.0 executes the recalled command. 

Discards all the characters left of the cursor and moves the 
cursor to the beginning of the current line. CTRL-X saves 
any characters to the right of the cursor. 
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Table 14-5. CP/M 3.0 Line-Editing Control Characters 
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MAKING COPIES WITH A 
SINGLE DISK DRIVE 

You can copy the contents of a disk with a single Commodore disk drive (1541 or 
1571). For example, use the following sequence of commands to create a bootable 
CP/M system disk. First type: 

A>FORMAT 

and follow the instructions given on the screen. When the copy disk is formatted, 
type: 



n A>PIP E: = A:CPM + .SYS 

When the CPM + SYS file is copied, you type: 
P A>PIP E: = A:CCP.COM 

To copy everything on a disk, use the following command sequence: 

A>FORMAT 
A>PIPE: = A:*.* 

The system prompts the user to change disks as required. 

Use drive A as the source drive and drive E as the destination drive. Drive E is 
referred to as a virtual drive; that is, it does not exist as an actual piece of hardware — it is 
strictly a logical drive. 

MAKING COPIES WITH TWO DISK DRIVES 

You can back up disks in CP/M by using two drives: drive A and drive B. The drives 
can be named with other letters from A through D. To make a copy of your CP/M 3.0 
system disk, first use the FORMAT utility to copy the operating system loader. Make 
sure that the CP/M system disk is in drive A, the default drive, and the blank disk is in 
drive B. Then enter the following command at the system prompt: 

A>PIPB: =A:CPM+.SYS 

When you have copied the CPM + . SYS file, use the PIP command to copy the 
CCP.COM file. This provides a copy of the operating system only. To copy all of 
the files from the system disk, enter the following PIP command: 

A>PIPB: = A:*.* 

This PIP command copies all the files on the disk in drive A to the disk in drive B. PIP 
displays the message COPYING, followed by each filename as the copy operation 
proceeds. When PIP finishes copying, the system prompt (A>) is displayed. 
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GENERAL CP/M 3.0 SYSTEM LAYOUT 



CP/M 3.0 OPERATING SYSTEM 
COMPONENTS 



u 
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The Commodore 128 computer is a two-processor system, with the 8502 as the primary 
processor and the Z80 as the secondary processor. The 8502 has the same instruction set 
as the 6502. The Z80's primary function is to run CP/M 3.0. This section describes the j j 

general requirements and methods for implementing CP/M 3.0 on the C128. |j 

When CP/M is running, the normal functions of the CI 28 are not supported 
(CP/M and BASIC cannot run at the same time). Also, CP/M does not directly support 
all the display modes of the VIC chip. (An application could be written to run under j 

CP/M that could use additional graphics capabilities, but the application would have to 
keep track of all the details, such as memory maps). 



u 



The CP/M 3.0 operating system consists of the following three modules: the Console 
Command Processor (CCP), the BASIC Disk Operating System (BDOS), and the Basic 
Input Output System (BIOS). 

The CCP is a program that provides the basic user interface to the facilities of the 
operating system. The CCP supplies the six built-in commands: DIR, DIRS, ERASE, ^ 

RENAME, TYPE, and USER. The CCP executes in the Transient Program Area 
(TPA), the region of memory where all application programs execute. The CCP contains 
the Program Loader Module, which loads transient (applications) programs from disk L 

into the TPA for execution. On the Commodore 128, a 58K to 59K TPA area is provided 
for CP/M. j 

The BDOS is the logical nucleus and file system of CP/M 3.0. The BDOS [_ 

provides the interface between the application program and the physical input/output 
routines of the BIOS. i 

The BIOS is a hardware-dependent module that interfaces the BDOS to a particu- [ 

lar hardware envfa-onment. The BIOS performs all physical I/O in the system. The BIOS 
consists of a number of routines that are configured to support the specific hardware of 
the target computer system (in this case, the Commodore 128). 

The BDOS and the BIOS modules cooperate to provide the CCP and other 
transient programs with hardware-independent access to CP/M 3.0 facilities. Because 
the BIOS can be configured for different hardware environments and the BDOS remains 1 

constant, you can transfer programs that run under CP/M 3.0 to systems with different L 

hardware configurations. 

COMMUNICATION BETWEEN MODULES L 

The BIOS loads the CCP into the TPA at system cold and warm starts. The CCP moves 
the Program Loader Module to the top of the TPA and uses the Program Loader Module 
to load transient programs. '— ' 
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The BDOS contains a set of functions that the CCP and applications programs call 

to perform disk and character input and output operations. 
i I The BIOS contains a Jump Table with a set of thirty-three entry points that the 

I I BDOS calls to perform hardware-dependent primitive functions, such as peripheral 

device I/O. For example, CONIN is an entry point of the BIOS called by the BDOS to 
r-» read the next console input character. 

I I Similarities exist between the BDOS functions and BIOS functions, particularly 

for simple device I/O. For example, when a transient program makes a console output 
^ function call to the BDOS, the BDOS makes a console output call to the BIOS. In the 

j I case of disk I/O, however, this relationship is more complex. The BDOS file may make 

' ' many BIOS function calls to perform a single BDOS file I/O function. BDOS disk I/O is 

in terms of 128-byte logical records. BIOS disk I/O is in terms of physical sectors and 
n tracks. 

I I The System Control Block (SCB) is a 100-byte (decimal) CP/M 3.0 data structure 

that resides in the BDOS system component. The BDOS and the BIOS communicate 
r-i through fields in the SCB. The SCB contains BDOS flags and data, CCP flags and data, 

I I and other system information, such as console characteristics and the current date and 

time. You can access some of the System Control Block fields from the BIOS. 

Note that the SCB contains critical system parameters that reflect the current state 
n of the operating system. If a program modifies these parameters, the operating system 

■ I can crash. See Section 3 of the DRI CP/M Plus System Guide and the description of 

BDOS Function 49 in the DRI CP/M Plus Programmer's Guide for more information on 
r^ the System Control Block. 

I I Page zero is a region of memory that acts as an interface between transient 

programs and the operating system. Page zero contains critical system parameters, includ- 
„ ing the entry to the BDOS and entry to the BIOS Warm BOOT routine. At system 

j j start-up, the BIOS initializes these two entry points in page zero. All linkage between 

transient programs and the BDOS is restricted to the indirect linkage through page zero. 



! i 



CP/M 3.0 BIOS OVERVIEW 



This section describes the organization of the CP/M 3.0 BIOS and the BIOS jump 
vector. It provides an overview of the System Control Block, followed by a discussion 
of system initialization procedures, character I/O, clock support, disk I/O, and memory 
selects and moves. 

ORGANIZATION OF THE BIOS 

The BIOS is the CP/M 3.0 module that contains all hardware-dependent input and 
output routines. To configure CP/M 3.0 for a particular hardware environment, the 
sample BIOS supplied with the CP/M Plus System Guide must be adapted to the specific 
hardware of the target system (the Commodore 128). 

The BIOS essentially is a set of routines that performs system initialization, 
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character-oriented I/O to the console and printer devices, and physical sector I/O to disk 
devices. The BIOS also contains routines that manage block moves and memory selects 
for bank-switched memory. The BIOS supplies tables that define the layout of the disk 
devices and allocate buffer space that the BDOS uses to perform record blocking and 
deblocking. The BIOS can maintain the system time and date in the System Control Block. 
Table 14-6 describes the entry points into the BIOS from the Cold Start Loader 
and the BDOS. Entry to the BIOS is through a set of jump vectors. The jump table is 
a set of thirty-three jump instructions that pass program control to the individual BIOS 
subroutines. 
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NO. INSTRUCTION 



2 
3 
4 
5 
6 
7 



JMP 

1 JMP 
JMP 
JMP 
JMP 
JMP 
JMP 
JMP 

8 JMP 

9 JMP 

10 JMP 

11 JMP 

12 JMP 

13 JMP 

14 JMP 

15 JMP 

16 JMP 

17 JMP 

18 JMP 

19 JMP 

20 JMP 

21 JMP 

22 JMP 

23 JMP 

24 JMP 

25 JMP 

26 JMP 

27 JMP 

28 JMP 

29 JMP 

30 JMP 

31 JMP 

32 JMP 



BOOT 

WBOOT 

CONST 

CONIN 

CONOUT 

LIST 

AUXOUT 

AUXIN 

HOME 

SELDSK 

SETTRK 

SETSEC 

SETDMA 

READ 

WRITE 

LISTST 

SECTRN 

CONOST 

AUXIST 

AUXOST 

DEVTBL 

DEVINI 

DRVTBL 

MULTIO 

FLUSH 

MOVE 

TIME 

SELMEM 

SETBNK 

XMOVE 

USERF 

RESERVl 

RESERV2 



DESCRIPTION 

Perform cold start initialization. 

Perform warm start initialization. 

Check for console input character ready. 

Read console character in. 

Write console character out. 

Write list character out. 

Write auxiliary output character. 

Read auxiliary input character. 

Move to Track 00 on selected disk. 

Select disk drive. 

Set track number. 

Set sector number. 

Set DMA address. 

Read specified sector. 

Write specified sector. 

Return list status. 

Translate logical to physical sector. 

Return output status of console. 

Return input status of aux. port. 

Return output status of aux. port. 

Return address of char. I/O table. 

Initialize char. I/O devices. 

Return address of disk drive table. 

Set number of logically consecutive sectors to be read or 

written. 
Force physical buffer flushing for user-supported deblocking. 
Memory to memory move. 
Time set/get signal. 
Select bank of memory. 
Specify banks for inter-bank MOVE. 
Set banks for an inter-bank MOVE. 
Commodore CP/M system functions. 
Reserved for future use. 
Reserved for future use. 
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Table 14-6. CP/M 3.0 BIOS Jump Vectors 
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All the entry points in the BIOS jump vector are included in the C128 CP/M 3.0 

BIOS. 

1] Each jump address in Table 14-6 corresponds to a particular subroutine that 

performs a specific system operation. Note that two entry points are reserved for future 

versions of CP/M, and one entry point is provided for the Commodore system functions. 

Table 14-7 shows the five categories of system operations and the function calls 
that accomplish these operations. 



OPERATION FUNCTION 

System BOOT, WBOOT, DEVTBL, DEVINI, DRVTBL 

Initialization 

Cliaracter I/O CONST, CONIN, CONOUT, LIST, AUXOUT, AUXIN, LISTST, 
CONOST, AUXIST, AUXOST 

Disk: I/O HOME, SELDSK, SETTRK, SETSEC, SETDMA, READ, WRITE, 

SECTRN, MULTIO, FLUSH 

Memory Selects MOVE, SELMEM, SETBNK, XMOVE 
and Moves 

Clock Support TIME 

Table 14-7. CP/M 3 BIOS Functions 

Appendix K illustrates how to call a Commodore CP/M system function in Z80 
machine language. 



SYSTEM MEMORY 
ORGANIZATION 

Figure 14-1 shows the general memory organization of CP/M 3.0. 
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Figure 14-1. CP/M 3.0 General Memory Organization 
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The memory map is limited to 64K at any one point in time. However, the RAM 
bank can be selected and then different ROM areas can overlay the RAM (with 
bleed-through on write operations). The actual memory map is controlled by the MMU. The 
MMU can be accessed in the I/O area (only when I/O is enabled in Z80 space) or 
through the Load Configuration Register located at FFOO through FF04. . 

If the Load Configuration Registers are read, then the current value is read. A 
write to FFOO changes the configuration after completing the current instruction. A 
write to ITOl to FF04 updates the current configuration to the value stored in the 
Preconfiguration Registers (the data written is not used). The MMU page pointers have 
both a low (page) and a high (page) pointer. The high is written first and latched in the 
MMU; the high value is updated from the latch when the low byte is written. The MMU 
Control Registers are listed in Chapter 13. 



DISK ORGANIZATION 

CP/M 3.0 supports a number of different disk formats, including three Commodore 
formats and a number of MFM formats. (MFM is the industry standard format.) The 
first Commodore format is single-sided Commodore OCR, which is compatible with the 
CP/M 2.2 that runs on the Commodore 64. With this format, the File Control Block 
(FCB) is set up as 32 tracks of 17 sectors each and a track offset of 2. The BIOS routine 
adds a 1 to tracks greater than 18 (this is the C64 directory track). 
i ! The second format, known as the C128 CP/M Plus disk format, is new and is also 

single-sided. This format, which is also a OCR format, takes advantage of the full disk 
capacity by setting up the FCB with 638 tracks of 1 sector each and a track offset of 0. 
This has the effect of having CP/M set the track to the block number relative to 
the beginning of the disk, with the sector always set to 0. The following algorithm is 
used to convert the requested TRACK to a real track and sector number. 



REQUESTED TRACK ACTUAL TRACK 

000 > = TRACK > 355 ((TRACK + 2)/21) + 1 

355 > = TRACK > 487 ((TRACK - 354)/19) + 18 

487 > = TRACK > 595 ((TRACK - 487)/18) + 25 

595 > = TRACK > 680 ((TRACK - 595)/17) + 31 

680 > = TRACK > 1360 SET SIDE 2 TRACK = TRACK - 680 
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The effective sector is then translated to provide a skew that speeds up operations. 
The skew is used only with the new larger format. A different skew table is used for 
each region of the disk. 

The third Commodore format is a GCR double-sided format. The disk is treated as 
1276 sectors of data with a track offset of 0. Side 1 is used first; then side 2 is used. 



NOTE: This is not the usual way to handle a two-sided disk; however, 
allocating the disk in this manner, the user with a 1541 may still be able 
to read data written at the start of a two-sided disk. 



The third Commodore format and all MFM formats require that the user have the 
new 1571 disk drive. This disk drive supports both single- and double-sided diskettes 
and both the Commodore GCR and industry standard MFM data coding formats. 

The following table summarizes 1541/1571 disk drive capabilities with regard to 
the various disk formats. 







DISK FORMAT 


1541 DRIVE 


1571 DRIVE 


C64 GCR 
single-sided 


y 


y 


€128 GCR 
single-sided 


y 


y 


€128 GCR 
double-sided 




y 


MFM 
format 




y 



u 



C64 CP/M DISK FORMAT 
(SINGLE-SIDED) 

This format, shown in Figure 14-2, is provided to allow the user to read/write files 
created using the C64 CP/M 2.2 cartridge. (However, do not use the CP/M 2.2 cartridge 
with the C128.) Notice the unused space in this format. 
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SECTOR 

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 

OBBBBBBBBBBBBBBBBB x x x x 

IBBBBBBBBBBBBBBBBB x x x x 

2 xxxx 

3 



xxxx 

' i 5 



I ^ xxxx 



xxxx 

^ xxxx 

•~1 ' xxxx 

I * xxxx 

' 'i 9 

' xxxx 

*" xxxx 

rn ^* xxxx 

j ^^ xxxx 

' 13 xxxx 

^^ xxxx 

^n * xxxx 

• I 16 xxxx 

!i 17DDDDDDDDDDDDDDDDDDD 

1* XX 

19 XX 

20 XX 

M 21 XX 

22 XX 

P-, 23 XX 

i i 24 X 

I j 25 X 

26 X 

27 X 

n 28 X 

) ( 29 X 

30 

31 

n 32 

i j 33 

34 

1-n . Used by CP/M. 

j 1 B Boot Sector (System). 

I ' D Directory Sector (Disk DOS). 

X Not used by CP/M. 

I I Frgure 14-2. C64 C/PM Disk Format 

C 1 28 CP/M DISK FORMATS 
j I (SINGLE- AND DOUBLE-SIDED) 

Figure 14-3 shows the C128 CP/M Plus format for a single-sided disk. 



494 COMMODORE 128 



SECTOR 

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 

OB....X 

1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

16 

17 

18 D 

19 

20 

21 

22 

23 

24 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

. Used by CP/M, reg. = region (1-4). 

B Boot Sector (System). 

D Directory Sector (Dlslc DOS). 

X Not used by CP/M. 

SKEW TABLE 
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 

1 00 17 13 09 05 01 18 14 10 06 02 19 15 11 07 03 20 16 12 08 04 

2 00 04 08 12 16 01 05 09 13 17 02 06 10 14 18 03 07 11 15 

3 00 11 04 15 08 01 12 05 16 09 02 13 06 17 10 03 14 07 

4 00 07 14 04 11 01 08 15 05 12 02 09 16 06 13 03 10 



u 
u 







IJ 



Figure r4-3. CI28 CP/M Plus Disk Format 
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NOTE: This format is duplicated on the second side of a two-sided disk 
(with the exception of B, which is unused and therefore becomes X). 



MFM DISK FORMATS 

A number of MFM disk formats are built into CP/M on the C128. These formats, which 
can be selected at the time a program is to be run, include Osborne, Kaypro, Epson and 
IBM CP/M-86. The IBM CP/M-86 capability is provided so that data can be transferred 
between machines. However CP/M-86 programs cannot be run on the C128, since on 
the CI 28, CP/M Plus runs on a Z80, not an 8088. 

When used with the 1571 Disk Drive, the Commodore 128 supports a variety 
of double-density MFM disk formats (for reading and/or writing), including: 

Epson QXIO (512 byte sectors, double-sided, 10 sectors per track) 

IBM-8 SS (CP/M 86) (512 byte sectors, single-sided, 8 sectors per track) 

IBM-8 DS (CP/M 86) (512 byte sectors, double-sided, 8 sectors per track) 

KayPro II (512 byte sectors, single-sided, 10 sectors per track) 

Kay Pro IV (512 byte sectors, double-sided, 10 sectors per track) 

Osborne DD (1024 byte sectors, single-sided, 5 sectors per track) 

When you insert one of these disks into the disk drive and try to access it, the system 
senses the type of disk with respect to the number of bytes per sector and the number of 
sectors per track. If the disk format is not unique, a box is displayed near the bottom-left 
comer of the screen, showing which disk type you are accessing. The system requires 
you to select the specific disk type by scrolling through the choices given in this 
window. 



NOTE: The choices are given one at a time; scroll through using the 
right and left arrow keys. Press RETURN when the disk type that 
you know is in the disk drive is displayed. Press CONTROL 
RETURN to lock this di^k format so that you will not need to 
select the disk type each time you access the disk drive. 
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KEYBOARD SCANNING 

The keyboard scan routine that is called to get a keyboard character returns the key code LJ 

of the pressed key, or a code indicating that no key is currently being pressed. The 
keyboard scan code is also responsible for handling progranimable keys, programmable ) i 

function keys, setting character and background colors, selecting MFM disk formats and ij 

selecting current screen emulation type. 

Any key on the keyboard can be defined to generate a code or function except the 
following keys: 1 

LEFT SHIFT 

RIGHT SHIFT } ( 

SHIFT LOCK Li 

O 

CONTROL . I 

RESTORE (8502 NMI) I 

40/80 DISPLAY 

CAPS LOCK KEY 

The keyboard recognizes the following special functions: j 

Cursor left key-Used to define a key 

Cursor right key-Used to define a string ] 

(points to function keys) 

ALT key-Used as toggle key filter , , 

To indicate these functions, hold down the CONTROL key and the '—^ 

RIGHT SHIFT key and simultaneously press the desired function key. 

DEFINING A KEY LJ 

The KEYFIG utility program allows the user to define the code that a key can produce. 

Each key has four modes of use for this function: | 

■ Normal 

■ Alpha shift , , 

■ Shift j 

■ Control ^ 

The alpha shift mode is toggled on/off by pressing the Commodore (O) key. When ) I 

this mode is turned on, a small white box appears on the bottom of the screen. The first !j 

key that is pressed thereafter is the key to be defined. The current hex value assigned to 

this key is displayed, and the user can then type the new hex code for the key, or abort 

by typing a non-hex key. The following is a definition of the codes that can be assigned i 

to a key. See KEYFIG HELP for more information. i-l 

u 
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CODE FUNCTION 

OOh Null (same as not pressing a key) 

Olh to 7Fh Normal ASCH codes 

80h to 9Fh String assigned 

AOh to AFh 80-column character color 

BOh to BFh 80-column background color 

COh to CFh 40-column character color 

DOh to DFh 40-column background color 

EOh to EFh 40-colunm border color 

FOh Toggle disk status on/off 

Flh System Pause 

F2h (Undefmed) 

r-j F3h 40-column screen window right 

> j F4h 40-column screen window left 

' ' FShtoFFh (Undefmed) 

! DEFINING A STRING 

r-, The DEFINE STRING function allows the user to assign more than one key code to a 

j j single key. Any key that is typed in this mode is placed in the string. The user can see 

the results of typing in a long box at the bottom of the screen. Note, however, that some 

^_^ keys may not display what they are. 

i i To allow the user control of entering data, five special edit functions are provided. 

To access any of these functions, you first press the CONTROL and RIGHT 
SHIFT keys. (This allows the user to enter any key into the buffer.) 

r^ The functions assigned to the five string edit keys are as follows: 



KEY FUNCTION 

RETURN End string definition. 

+ symbol* Insert space in string. 

- symbol* Delete cursor character. 

Right Cursor Move cursor to right. 

Left Cursor Move cursor to left. 



*0n main keyboard only. 

ALT MODE 

This function is a toggle (on/off) and is provided to allow the user to send 8-bit 
codes to an application without the keyboard driver "eating" the code from 80h to 
FFh. 
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UPDATING THE 

40/80 COLUMN DISPLAY 



TERMINAL EMULATION PROTOCOLS 



FUNCTION 


CHARACTER SEQUENCE 




HEX CHAR CODE 


Position Cursor 


ESC(row# + 32)(col#+32) 


IB 3D 20+ 20 + 


Cursor Left 


Control H 




08 


Cursor Riglit 


Control L 




OC 


Cursor Down 


Control J 




OA 


Cursor Up 


Control K 




OB 


Home and Clear Screen 


Control Z 




lA 


Carriage Return 


Control M 




OD 


Escape 


Control [ 




IB 


BeU 


Control G 




07 


NOTE: Display is 24 (1-24) by 80 (1-80); cursor origin is 


always 1/1. 



Figure 14-4. Lear Siegier ADM-3A Protocol 
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As noted elsewhere in this book, there are two different display systems within 

the C128. The first, which is controlled by the VIC chip, produces a 25-line by 

40-column display, has many graphics modes of operation, and can be used with a IJ 

standard color (or black-and-white) television or color monitor. (See Chapters 8 and 9 

for details.) The only VIC-controlled display mode used by CP/M is standard character j / 

mode, with each character and screen background having up to sixteen colors. \i 

The second display system available in CI 28 CP/M is controlled by the 8563 
display controller. The display format of this controller is 25 lines by 80 columns, with 
character color attributes. The VIC chip is a memory-mapped display, and the 8563 is j j 

I/O-controUed. The two display subsystems are treated as two separate displays. CP/M ^-> 

3.0 can assign one or both to the console output device. 

Both displays are controlled by a common terminal emulation package, a Lear 
Siegier ADM-31 (ADM-3A is a subset of this) driver. The terminal driver is divided 
into two parts: terminal emulation and terminal functions. Terminal emulation is 
handled by the Z80 BIOS, and the terminal function is handled primarily in the 
Z80 ROM. 

The following section shows the various terminal emulation protocols supported 
by Commodore 128 CP/M. 
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NOTE: The following have been added to allow the system to emulate 
the KayPro II display more closely. 



FUNCTION 



Home Cursor 

CEL (Clear to End of Line) 

CES (Clear to End of Screen) 



CHARACTER 

SEQUENCE 

Control t 
Control-X 
Control-W 





CHARACTER SEQUENCE 


HEX CHARACTER CODES 




Clear to end of line 


ESCT 
ESCt 




IB 54 
IB 74 




Clear to end of screen 


ESCY 
ESCy 




IB 59 
IB 79 




Home cursor and clear screen 


ESC: 

ESC* 




1B3A 
IB2A 




Half intensity on 


ESC) 




IB 29 




Half intensity off 


ESC( 




IB 28 




Reverse video on 


ESCG4 




IB 47 34 




Blinking on 


ESCG2 




IB 47 32 




Underline on * 


ESCG3 




IB 47 33 




Select alternate character set* 


ESCGl 




IB 47 31 




Reverse video and blinking off 


ESC GO 




IB 47 30 




Insert line 


ESCE 




IB 45 




Insert character 


ESCQ 




IB 51 




Delete line 


ESCR 




IB 52 




Delete character 


ESC W 




IB 57 




Set screen colors* 


ESC ESC ESC color # 








where color # 


= 20h to 2Fh — character color 








30h to 3Fh — background color 


Physical 






40h to 4Fh— border color (40 


Colors 








columns only) 








50h to SOFh— character color 








60h to 60Fh — background color 


Logical 






70h to 70Fh— border color (40 


Colors 








columns only) 




♦Indicates this is not a normal ADM31 sequence. 








Note: Display is 24 (1-24) by 80 (1-80); cursor origin 


s always 1/1. 





Figure 14-5. Lear Siegler ADM-3i Protocol 
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SYSTEM OPERATIONS 



SETTING SYSTEM TIME 



For more information on the general (non-Commodore 128-dependent) CP/M 3.0 
system, see tiie offer in section 15 of the CI 28 System Guide for the Digital Research 
CP/M Plus User's Guide, Programmer's Guide and System Guide. 



LJ 



) I 



The time of day is set with this function. The time of day is stored in packed BCD 

format in the System Control Block (SCB) in three locations (hours, minutes, seconds). 

This routine reads the SCB time and writes that time to the time of day clock within the LJ 

6526. This time is updated on the chip and is used by CP/M. The Z80 is able to 

read/write the 6526 directly. | { 

UPDATING SYSTEM TIME 

The SCB time is updated from the time of day clock on the 6526 by doing a system call. j ) 

8502 BIOS ORGANIZATION IJ 

The 8502 is responsible for most of the low-level I/O functions. The request for these , , 

functions is made through a set of mailboxes. Once the mailboxes are set up, the Z80 Ij 
shuts down and the 8502 starts up (BIOS85). The 8502 looks at the command in the 
mailbox and performs the required task, sets the command status and shuts down. The 

Z80 is re-enabled; it then looks at the command status and takes the appropriate actions. 1 

The 8502 BIOS commands are defined in Appendix K. <~ 

This concludes the summary explanation of the Conmiodore 128 CP/M system. \ j 

However, the Commodore 128 CP/M System includes many additional Commodore |j 
128-dependent routines and functions that are performed by the Z80 microprocessor. 
Since most of these routines, system calls and functions are tabular information, they are 

covered in Appendix K. For information on any of the following topics, refer to j 

Appendix K. ^ 

8502 BIOS commands \ 

All Commodore 128 Z80 system-dependent user functions L 

Calling a CP/M BIOS, 8502 BIOS and CP/M User system functions in Z80 machine 

language 

More information on MFM disk formats 

Commodore 128 CP/M (Z80) Memory Map 
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This chapter provides the memory maps for both C128 and C64 modes. A memory map 
tells you exactly how memory is laid out internally in both RAM and ROM. It tells you 
exactly what resides in each memory location. The memory map directs you in finding 
address vectors for routines and entry points and provides information about the general 
layout of the computer. The memory map is probably the most vital programming tool. 
Refer to the memory map whenever you need directions throughout the memory of your 
Commodore 128. Addresses listed with more than one address label are used for more 
than one purpose. To BASIC, the variable has one purpose; to the Machine Language 
Monitor, it may have another. 
The conventions used for the memory maps are as follows: 



Column 1 

MEMORY 
ADDRESS 
LABEL 



Column 2 



Column 3 Column 4 



HEXADECIMAL DECIMAL 

ADDRESS ADDRESS DESCRIPTION 



See Appendix K for the Z80 memory map for CP/M on the Commodore 128. 
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CI28 MEMORY MAP 













MEMORY 










ADDRESS 


HEXADECIMAL 


DECIMAL 




\ 


LABEL 


ADDRESS 


ADDRESS 


DESCRIPTION 


) 


D6510 


0000 





6510 DATA DIRECTION REGISTER 




R6510 


0001 


1 


6510 DATA REGISTER 


1 


BANK 


0002 


2 


TOKEN 'SEARCH' LOOKS FOR, OR 
BANK# 


i 


PC_HI 


0003 


3 


ADDRESS FOR BASIC SYS 
COMMAND OR MONITOR AND 
LONG CALL/JUMP ROUTINES 


\ 
1 


PC_LO 


0004 


4 


ADDRESS, STATUS, A-REG, X-REG, 
Y-REG 


LJ 


S-REG 


0005 


5 


STATUS REG TEMP 


\ 


A REG 


0006 


6 


.A REG TEMP 


j 


X REG 


0007 


7 


.X REG TEMP 


'— ' 


Y_REG 


0008 


8 


.Y REG TEMP 




STKFIR 


0009 


9 


STACK POINTER TEMP 


1 



INTEGR 

CHARAC 

ENDCHR 

TRMPOS 
VERCK 



BASIC ZERO PAGE STORAGE 
0009 9 



OOOA 

OOOB 
OOOC 



SEARCH CHARACTER 

10 FLAG: SCAN FOR QUOTE AT END 
OF STRING 

11 SCREEN COLUMN FROM LAST TAB 

12 FLAG: = LOAD, 1 = VERIFY 



y 
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C128 Memory Map (continued) 








MEMORY 








1 ; 


ADDRESS 


HEXADECIMAL 


DECIMAL 




1 ! 


LABEL 


ADDRESS 


ADDRESS 


DESCRIPTION 




COUNT 


OOOD 


13 


INPUT BUF.PTR / # OF SUBSCRIPTS 


,_ 


DIMFLG 


OOOE 


14 


FLAG: DEFAULT ARRAY DIMENSION 


, 1 


VALTYP 


OOOF 


15 


DATA TYPE: $FF = STRING, 
$00 = NUMERIC 




INTFLG 


0010 


16 


DATA TYPE: $00=FLOAT.PT, 


rn 








$80 = INTEGER 


1 ! 

, 1 


GARBFL 


0011 


17 


FLAG: DATA SCAN / LIST QUOTE / 
GARBAGE COLLECTION 




DORRS 








i > 


SUBFLG 


0012 


18 


FLAG: SUBSCRIPT REF. / USER 
FUNC. CALL 


( i 


INPFLG 


0013 


19 


FLAG: $00 = INPUT, $40 = GET, 
$98= READ 


1 
1 
1 


DOMASK 


0014 


20 




TANSGN 






FLAG: TAN SIGN / COMPARISON 










RESULT 




CHANNL 


0015 


21 




n 


POKER 
LINNUM 


0016 


22 


TEMP INTEGER VALUE 




TEMPPT 


0018 


24 


POINTER: TEMP STRING STACK 




LASTPT 


0019 


25 


LAST TEMP STRING ADDRESS 


— 1 


TEMPST 


OOIB 


27 


STACK FOR TEMP STRINGS 


i 
j 


INDEX 


0024 


36 


UTILITY POINTER AREA 




INDEXl 










INDEX2 


0026 


38 




( t 


RESHO 


0028 


40 


FLOAT.pt. PRODUCT OF MULTIPLY 


\ 

, 1 


RESMOH 


0029 


41 






ADDEND 


002A 


42 






RESMO 








n 


RF.SLO 


002B 


43 




/ i 


TXTTAB 


002D 


45 


POINTER: START OF BASIC TEXT 


f"^ 


VARTAB 


002F 


47 


POINTER: START OF BASIC 
VARIABLES 


) 


ARYTAB 


0031 


49 


POINTER: START OF BASIC ARRAYS 


1 


STREND 


0033 


51 


POINTER: END OF BASIC ARRAYS 

+ 1 


{ i 


FRETOP 


0035 


53 


POIN lER: BOTTOM OF STRING 
STORAGE 


t 

! \ 


FRESPC 


0037 


55 


UTILITY STRING POINTER 




MAX_MEM_1 


0039 


57 


TOP OF STRING/VARIABLE BANK 
(BANK 1) 


i i 


CURLIN 


003B 


59 


CURRENT BASIC LINE NUMBER 


( 1 


TXTPTR 


003D 


61 


POINTER TO BASIC TEXT USED BY 
CHRGET,ETC. 


^^ 


FORM 


003F 


63 


USED BY PRINT USING 


1 


FNDPNT 






POINIER TO ITEM FOUND BY 



SEARCH 
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C128 Memory Map (continued) 



MEMORY 
ADDRESS 
LABEL 



HEXADECIMAL DECIMAL 
ADDRESS ADDRESS 



DESCRIPTION 



BASIC ZERO PAGE STORAGE 



DATLIN 


0041 


65 


DATPTR 


0043 


67 


INPPTR 


0045 


69 


VARNAM 


0047 


71 


FDECPT 


0049 


73 


VARPNT 






LSTPNT 


004B 


75 


FORPNT 






ANDMSK 






EORMSK 


004C 


76 


VARTXT 


004D 


77 


OPPTR 






OPMASK 


004F 


79 


GRBPNT 


0050 


80 


TEMPF3 






DEFPNT 






DSCPNT 


0052 


82 




0054 


84 


HELPER 


0055 


85 


JMPER 


0056 


86 




0057 


87 


OLDOV 


0058 


88 


TEMPFl 


0059 


89 


PTARGl 






PTARG2 


005B 


91 


STRl 


005D 


93 


STR2 


0060 


96 


posrm 


0063 


99 


MATCH 


0064 


100 


ARYPNT 


005A 


90 


HIGHDS 






HIGHTR 


005C 


92 


TEMPF2 


005E 


94 


DECCNT 


005F 


95 


TENEXP 


0060 


96 


TO 






GRBTOP 


0061 


97 


DFitLG 






Lowm 






EXPSGN 


0062 


98 


FAC 


0063 


99 



CURRENT DATA LINE NUMBER 
CURRENT DATA ITEM ADDRESS 
VECTOR: INPUT ROUTINE 
CURRENT BASIC VARIABLE NAME 

POINTER: CURRENT BASIC 
VARIABLE DATA 

POINTER: INDEX VARIABLE FOR 
FOR/NEXT 



FLAGS 'HELP' OR 'LIST' 



MULTIPLY DEFINED FOR INSTR 



NUMBER OF DIGITS AFTER THE 
DECIMAL POINT 

ML MONITOR Z.P. STORAGE IN 
FAC 

DECIMAL POINT FLAG 






\ { 



y 
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MEMORY 








ADDRESS 


HEXADECIMAL 


DECIMAL 




LABEL 


ADDRESS 


ADDRESS 


DESCRIPTION 




BASIC ZERO PAGE STORAGE 


DSCTMP 








LEFT-FLAG 






PAINT-LEFT FLAG 


FACEXP 






FAC#1 EXPONENT 


Tl 






MONITOR Z.P. STORAGE IN FAC 


RIGHT-FLAG 


0064 


100 


PAINT-RIGHT FLAG 


FACHO 






FAC#1 MANTISSA 


FACMOH 


0065 


101 




INDICE 


0066 


102 




FACMO 








T2 






MONITOR Z.P. STORAGE IN FAC 


FACLO 


0067 


103 




FACSGN 


0068 


104 


FAC#1 SIGN 


DEGREE 


0069 


105 




SGNFLG 






POINTER: SERIES-EVAL. CONSTANT 


ARGEXP 


006A 


106 


FAC#2 EXPONENT 


ARGHO 


006B 


107 


FAC#2 MANTISSA 


ARGMOH 


006C 


108 




INIT_AS_0 






JUST A COUNT FOR INIT 


ARGMO 


006D 


109 




ARGLO 


006E 


110 




ARGSGN 


006F 


111 


FAC#2 SIGN 


STRNGl 


0070 


112 




ARISGN 






SIGN COMPARISON RESULT: 
FAC#1 VS #2 


FACOV 


0071 


113 


FAC#1 LOW-ORDER (ROUNDING) 


STRNG2 


0072 


114 




POLYPI' 








CURTOL 








FBUFPT 






POINTER: CASSETTE BUFFER 


AUTBSC 


0074 


116 


INC. VAL FOR AUTO {0 = OFF) 


MVDFLG 


0076 


118 


FLAG IF lOK HIRFS ALLOCATED 


7, P TEMP 1 


0077 


119 


PRINT USING'S LEADING ZERO 

COUNl'ER 

MOVSPR & SPRITE TEMPORARY 

MID$ TEMPORARY 


HULP 


0078 


120 


COUNTER 


KFYSIZ 








SYNTMP 


0079 


121 


USED AS TEMP FOR INDIRECT 
LOADS 


DSDESC 


007A 


122 


DESCRIPTOR FOR DS$ 


TXTPTR 






MONITOR Z.P. STORAGE 


TOS 


007D 


125 


TOP OF RUN IIME STACK 


RUNMOD 


007F 


127 


FLAGS RUN/DIRECT MODE 


PARSTS 


0080 


128 


DOS PARSER STATUS WORD 


POINT 






USING'S POINTER TO DEC.PT 



506 COMMODORE 128 



C128 Memory Map (continued) 



MEMORY 
ADDRESS 
LABEL 



HEXADECIMAL DECIMAL 
ADDRESS ADDRESS 



DESCRIPTION 



PARSIX 


0081 


OLDSTK 


0082 


BASIC Z-P 


COLSEL 


0083 


MULTICOLOR_l 


0084 


MULTICOLOR-! 


0085 


FOREGROUND 


0086 


SCALEJi 


0087 


SCALE_Y 


0089 


STOPNB 


008B 


GRAPNT 


008C 


VTEMPl 


008E 


VlEMPl 


008F 


STATUS 


0090 


STKEY 


0091 


SVXT 


0092 


VERCK 


0093 


C3P0 


0094 


BSOUR 


0095 


SYNO 


0096 


XSAV 


0097 


LDTND 


0098 


DFLTN 


0099 


DFLTO 


009A 


PRTY 


009B 


DPSW 


009C 


MSGFLG 


009D 


PTRl 


009E 


Tl 




PTRl 


009F 


T2 




TIME 


OOAO 


R2D2 


00A3 


PCNTR 




BSOURl 


00A4 


FIRT 




COU^JT 


00A5 


CNTDN 




BUFPT 


00A6 



BASIC ZERO PAGE STORAGE 

129 
130 



BASIC Z-P STORAGE FOR GRAPfflC COMMANDS 



131 
132 
133 
134 
135 
137 
139 

140 
142 
143 



KERNAL/EDITOR STORAGE 



CURRENT COLOR SELECTED 



SCALE FACTOR IN X 

SCALE FACTOR IN Y 

STOP PAINT IF NOT BACKGROUND/ 

NOT SAME COLOR 



144 I/O OPERATION STATUS BYTE 

145 STOP KEY FLAG 

146 TAPE TEMPORARY 

147 LOAD OR VERIFY FLAG 

148 SERIAL BUFFERED CHAR FLAG 

149 CHAR BUFFER FOR SERIAL 

150 CASSETTE SYNC # 

151 TEMP FOR BASIN 

152 INDEX TO LOGICAL FILE 

153 DEFAULT INPUT DEVICE # 

154 DEFAULT OUTPUT DEVICE # 

155 CASSETTE PARITY 

156 CASSETTE DIPOLE SWITCH 

157 OS MESSAGE FLAG 

158 CASSETTE ERROR PASSl 
TEMPORARY 1 

159 CASSETTE ERROR PASS2 
TEMPORARY 2 

160 24 HOUR CLOCK IN 1/60TH SECONDS 

163 SERIAL BUS USAGE 
CASSETTE 

164 TEMP USED BY SERIAL ROUTINE 

165 TEMP USED BY SERIAL ROUTINE 
CASSETTE SYNC COUNTDOWN 

166 CASSETTE BUFFER POINTER 



il 

u 






u 

U 
U 

1 
u 



u 
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MEMORY 
ADDRESS 
LABEL 
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HEXADECIMAL DECIMAL 

ADDRESS ADDRESS DESCRIITION 



KERNAL/EDITOR STORAGE 



INBIT 


00A7 


167 


SHCNL 






BITCI 


00A8 


168 


RER 






RINONE 


00A9 


169 


REZ 






RTOATA 


OOAA 


170 


RDFLG 






RIPRTY 


OOAB 


171 


SHCNH 






SAL 


OOAC 


172 


SAH 


OOAD 


173 


EAL 


OOAE 


174 


EAH 


OOAF 


175 


CMPO 


OOBO 


176 


TEMP 


OOBl 


177 


TAPEl 


00B2 


178 


Bins 


00B4 


180 


SNSWl 






NXTBIT 


00B5 


181 


DIFF 






RODATA 


00B6 


182 


PRP 






FNLEN 


00B7 


183 


LA 


00B8 


184 


SA 


00B9 


185 


FA 


OOBA 


186 


FNADR 


OOBB 


187 


ROPRTY 


OOBD 


189 


OCHAR 






FSBLK 


OOBE 


190 


DRIVE 


OOBF 


191 


MYCH 






CASl 


OOCO 


192 


TRACK 


OOCl 


193 


STAL 






SECTOR 


00C2 


194 


STAH 






MEMUSS 


0OC3 


195 


TMP2 






DATA 


00C5 


197 



RS-232 RCVR INPUT BIT STORAGE 

CASSETTE SHORT COUNT 

RS-232 RCVR BIT COUNT IN 

CASSETTE READ ERROR 

RS-232 RCVR FLAG FOR START BIT 

CHECK 

CASSETTE READING ZEROES 

RS-232 RCVR BYTE BUFFER 

CASSETTE READ MODE 

RS-232 RCVR PARITY STORAGE 

CASSETTE SHORT CNT 

POINTER: TAPE BUFFER / SCREEN 

SCROLLING 

TAPE END ADDRESSES / END OF 
PROGRAM 

TAPE TIMING CONSTANTS 

ADDRESS OF TAPE BUFFER 
RS-232 TRNS BIT COUNT 

RS-232 TRNS NEXT BIT TO BE SENT 

RS-232 TRNS BYTE BUFFER 

LENGTH CURRENT HLE N STR 
CURRENT FILE LOGICAL ADDR 
CURRENT FILE 2ND ADDR 
CURRENT HLE PRIMARY ADDR 
ADDR CURRENT FILE NAME STR 
RS-232 TRNS PARITY BUFFER 

CASSETTE READ BLOCK COUNT 

SERIAL WORD BUFFER 
CASSETTE MANUAL/CNTRLED 
SWITCH (UPDATED DURING IRQ) 

I/O START ADDRESS (LO) 

I/O START ADDRESS (HI) 
CASSETTE LOAD TEMPS (2 BYTES) 

TAPE READ/WRITE DATA 
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CI 28 Memory Map (continued) 



MEMORY 
ADDRESS 
LABEL 



HEXADECIMAL DECIMAL 
ADDRESS ADDRESS 



DESCRIPTION 



u 



KERNAL/EDITOR STORAGE 



BANK FOR CURRENT LOAD/SAVE/ 

VERIFY OPERATION 

BANK WHERE CURRENT FN IS 

FOUND (AT 'FNADR') 

RS-232 INPUT BUFFER POINTER 

RS-232 OUTPUT BUFFER POINTER 



KEYSCAN TABLE POINTER 
PRIMM UTILITY STRING POINTER 
INDEX TO KEYBOARD QUEUE 
PENDING FUNCTION KEY FLAG 
INDEX INTO PENDING FUNCTION 
KEY STRING 

KEYSCAN SHIFT KEY STATUS 
KEYSCAN CURRENT KEY INDEX 
KEYSCAN LAST KEY INDEX 
<CR> INPUT FLAG 
40/80 COLUMN MODE FLAG 
TEXT/GRAPHIC MODE FLAG 
RAM/ROM VIC CHARACTER FETCH 
FLAG (BIT-2) 

THE FOLLOWING LOCATIONS ARE SHARED BY SEVERAL EDITOR ROUTINES. 

POINTERS FOR MOVLIN 
TEMPORARY FOR TAB & LINE 
WRAP ROUTINES 

ANOTHER TEMPORARY PLACE TO 
SAVE A REG. 

SAVPOS 

PROGRAMMABLE KEY VARIABLES 



BA 


00C6 


198 


FNBANK 


00C7 


199 


RIBUF 


00C8 


200 


ROBUF 


OOCA 


202 




GLOBAL SCREEN El 


KEYTAB 


OOCC 


204 


IMPARM 


OOCE 


206 


NDX 


OODO 


208 


KYNDX 


OODl 


209 


KEYIDX 


00D2 


210 


SHFLAG 


00D3 


211 


SFDX 


00D4 


212 


LSTX 


00D5 


213 


CRSW 


00D6 


214 


MODE 


00D7 


215 


GRAPHM 


00D8 


216 


CHAREN 


00D9 


217 



u 



SEDSAL 


OODA 


218 


BITMSK 


OODA 


218 


SAVER 


OODB 


219 


SEDEAL 


OODC 


220 


SEDTl 


OODE 


222 


SEDT2 


OODF 


223 


KEYSIZ 


OODA 


218 


KEYLEN 


OODB 


219 


KEYNUM 


OODC 


220 


KEYNXT 


OODD 


221 


KEYBNK 


OODE 


222 


KEYTMP 


OODF 


223 



u 



PNT 
USER 



LOCAL SCREEN EDITOR VARIABLES. 

THESE ARE SWAPPED OUT TO $0A40 

WHEN SCREEN (40/80) MODE CHANGES. 



U 



OOEO 
00E2 



224 POINTER TO CURRENT LINE (TEXT) 

226 POINTER TO CURRENT LINE 

(ATTRIBUTE) 



n 

n 



n 
n 
n 



n 
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MEMORY 
ADDRESS 
LABEL 



HEXADECIMAL DECIMAL 
ADDRESS ADDRESS 



DESCRIPTION 



LOCAL SCREEN EDITOR VARIABLES. 

THESE ARE SWAPPED OUT TO $0A40 

WHEN SCREEN (40/80) MODE CHANGES. 



SCBOT 


00E4 


228 


SCTOP 


GOES 


229 


SCLF 


00E6 


230 


SCRT 


00E7 


231 


LSXP 


00E8 


232 


LSi'P 


00E9 


233 


INDX 


OOEA 


234 


TBLX 


OOEB 


235 


PNTR 


OOEC 


236 


LINES 


OOED 


237 


COLUMNS 


OOEE 


238 


DATAX 


OOEF 


239 


LSTCHR 


OOFO 


240 


COLOR 


OOFl 


241 


TCOLOR 


00F2 


242 


RVS 


00F3 


243 


QTSW 


00F4 


244 


INSRT 


OOFS 


245 


INSFLG 


00F6 


246 


LOCKS 


00F7 


247 


SCROLL 


OOFS 


248 


BEEPER 


00F9 


249 


FREKZP 


OOFA 


250 



WINDOW LOWER LIMIT 

WINDOW UPPER LIMIT 

WINDOW LEFT MARGIN 

WINDOW RIGHT MARGIN 

CURRENT INPUT COLUMN START 

CURRENT INPUT LINE START 

CURRENT INPUT LINE END 

CURRENT CURSOR LINE 

CURRENT CURSOR COLUMN 

MAXIMUM NUMBER OF SCREEN 

LINES 

MAXIMUM NUMBER OF SCREEN 

COLUMNS 

CURRENT CHARACTER TO PRINT 

PREVIOUS CHAR PRINTED (FOR 

<ESC> TEST) 

CURR ATTRIBUTE TO PRINT 

(DEFAULT FGND COLOR) 

SAVED ATTRIB TO PRINT ('INSERT' 

& 'DELETE') 

REVERSE MODE FLAG 

QUOTE MODE FLAG 

INSERT MODE FLAG 

AUTO-INSERT MODE FLAG 

DISABLES <SHIFT><&>, 

<CTRL>S 

DISABLES SCREEN SCROLL, LINE 

LINKER 

DISABLES <CTRL> G 

FREE ZERO PAGE RESERVED FOR 

APPLICATIONS SOFTWARE 

($FA-$FE) 



LOFBUF 



OOFF 



255 



BAD 
FBUFFR 

XCNT 



BASIC/DOS INTERFACE VARS 



0100 



0110 



256 TAPE READ ERRORS 

AREA TO BUILD FILENAME IN 

(16 BYTES) 
272 DOS LOOP COUNTER 
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C128 Memory Map (continued) 



u 



MEMORY 
ADDRESS 
LABEL 



NF 



HEXADECIMAL DECIMAL 
ADDRESS ADDRESS 



DESCRIPTION 



BASIC/DOS INTERFACE VARS 



DOSFIL 


0111 


273 


DOSDSl 


0112 


274 


D0SF2L 


0113 


275 


D0SDS2 


0114 


276 


D0SF2A 


0115 


277 


DOSOFL 


0117 


279 


DOSOFU 


0119 


281 


DOSLA 


OllB 


283 


DOSFA 


one 


284 


DOSSA 


OllD 


285 


DOSRCL 


OllE 


286 


DOSBNK 


OllF 


287 


DOSDID 


0120 


288 


DIDCHK 


0122 


290 


BNR 


0123 


291 


ENR 


0124 


292 


DOLR 


0125 


293 


FLAG 


0126 


294 


SWE 


0127 


295 


USGN 


0128 


296 


UEXP 


0129 


297 


VN 


012A 


298 


CHSN 


012B 


299 


VF 


012C 


300 



012D 



301 



POSP 


012E 


302 


FESP 


012F 


303 


ETOF 


0130 


304 


CFORM 


0131 


305 


SNO 


0132 


306 


BLED 


0133 


307 


BEGFD 


0134 


308 


LFOR 


0135 


309 


ENDED 


0136 


310 


SYSTK 


0137 


311 


BUF 


0200 


512 



DOS FILENAME 1 LEN 

DOS DISK DRIVE 1 

DOS FILENAME 2 LEN 

DOS DISK DRIVE 2 

DOS FILENAME 2 ADDR 

BLOAD/BSAVE STARTING ADDRESS 

....AND ENDING ADDRESS 

DOS LOGICAL ADDR 

DOS PHYS ADDR 

DOS SEC. ADDR 

DOS RECORD LENGTH 

DOS DISK ID 

DOS DSK ID FLG 

SPACE USED BY PRINT USING 

POINTER TO BEGIN. NO. 

POINTER TO END NO. 

DOLLAR FLAG 

COMMA FLAG 

COUNTER 

SIGN EXPONENT 

POINTER TO EXPONENT 

# OF DIGITS BEFORE DECIMAL 
POINT 

JUSTIFY FLAG 

# OF POS BEFORE DECIMAL POINT 
(HELD) 

# OF POS AFTER DECIMAL POINT 
(HELD) 

+/- FLAG (FIELD) 

EXPONENT FLAG (FIELD) 

SWITCH 

CHAR COUNTER (FIELD) 

SIGN NO 

BLANK/STAR FLAG 

POINTER TO BEGIN OF FIELD 

LENGTH OF FORMAT 

POINTER TO END OF FIELD 

SYSTEM STACK ($0137-$01FF) 

INPUT BUFFER: BASIC & MONITOR 

($0200-$02Al) 



u 
u 



IJ 



u 
U 



u 
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n 

! I 

n 



n 



n 



n 



n 
n 

n 



MEMORY 
ADDRESS 
LABEL 



FETCH 

FETVEC 

STASH 

STAVEC 

CMPARE 

CMPVEC 

JSRFAR 

JMPFAR 



HEXADECIMAL DECIMAL 
ADDRESS ADDRESS 



DESCRIPTION 



BASIC/DOS INTERFACE VARS 



02A2 
02AA 
02AF 
02B9 
02BE 
02C8 
02CD 
02E3 



ESC_FN_VEC 


02FC 


BNKVEC 


02FE 


lERROR 


0300 


IMAIN 


0302 


ICRNCH 


0304 


IQPLOP 


0306 


IGONE 


0308 


lEVAL 


030A 


lESCLK 


030C 


lESCPR 


030E 


lESCEX 


0310 


HRQ 


0314 


CINV 




IBRK 


0316 


CBINV 




INMI 


0318 


lOPEN 


031A 


ICLOSE 


031C 


ICHKIN 


031E 


ICKOUT 


0320 


ICLRCH 


0322 



674 


LDA(-),Y FROM ANY BANK 


682 




687 


STA(-),Y TO ANY BANK 


697 




702 


CMP(-),Y TO ANY BANK 


712 




716 


JSR XXXX TO ANY BANK & RETURN 


739 


JMP XXXX TO ANY BANK 


VECTORS 


764 


VECTOR FOR ADDITIONAL 




FUNCTION ROUTINES 


766 


VEC TOR FOR FUNCTION CART. 




USERS 


768 


VECTOR FOR PRINT BASIC ERROR 




(ERR IN .X) 


770 


VECTOR TO MAIN (SYSTEM DIRECT 




LOOP) 


772 


VECTOR TO CRUNCH 




(TOKENIZATION ROU IINE) 


774 


VECTOR TO LIST BASIC TEXT 




(CHAR LIST) 


776 


VECTOR TO GONE (BASIC CHAR 




DISPATCH) 


778 


VECTOR TO BASIC TOKEN 




EVALUATION 


780 


VECTOR TO ESCAPE-TOKEN 




CRUNCH, 


782 


...LIST, 


784 


...AND EXECUTE. 


788 


IRQ RAM VECTOR 



790 BRK INSTR RAM VECTOR 

792 NMI VECTOR 

794 KERNAL OPEN ROUTINE VECTOR 

796 KERNAL CLOSE ROUTINE VECTOR 

798 KERNAL CHKIN ROUTINE VECTOR 

800 KERNAL CHKOUT ROUTINE 

VECTOR 
802 KERNAL CLRCHN ROUTINE 

VECTOR 
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C128 Memory Map (continued) 



MEMORY 
ADDRESS 
LABEL 



HEXADECIMAL DECIMAL 
ADDRESS ADDRESS 



DESCRIFnON 







VECTORS 


IBASIN 


0324 


804 


IBSOUT 


0326 


806 


ISTOP 


0328 


808 


IGETIN 


032A 


810 


ICLALL 


032C 


812 


EXMON 


032E 


814 


ILOAD 


0330 


816 


ISAVE 


0332 


818 



KERNAL CHRIN ROUTINE VECTOR 
KERNAL CHROUT ROUTINE 
VECTOR 

KERNAL STOP ROUTINE VECTOR 
KERNAL GETIN ROUTINE VECTOR 
KERNAL CLALL ROUTINE VECTOR 
MONITOR COMMAND VECTOR 
KERNAL LOAD ROUTINE VECTOR 
KERNAL SAVE ROUTINE VECTOR 



EDITOR INDIRECT VECTORS 



CTLVEC 


0334 


820 


SHFVEC 


0336 


822 


ESCVEC 


0338 


824 


KEYVEC 


033A 


826 


KEYCHK 


033C 


828 


DECODE 


033E 


830 


KEYD 


034A 


842 


TABMAP 


0354 


852 


BITABL 


035E 


862 



LAT 


0362 


866 


FAT 


036C 


876 


SAT 


0376 


886 


CHRGET 


0380 


896 


CHRGOT 


0386 


902 


QNUM 


0390 


912 



EDITOR: PRINT 'CONTRL' INDIRECT 
EDITOR: PRINT 'SHIFTD' INDIRECT 
EDITOR: PRINT 'ESCAPE' INDIRECT 
EDITOR: KEYSCAN LOGIC INDIRECT 
EDITOR: STORE KEY INDIRECT 
VECTORS TO KEYBOARD MATRIX 
DECODE TABLES 
IRQ KEYBOARD BUFFER (10 BYTES) 

BITMAP OF TAB STOPS (10 BYTES, 
$0354-D) 

BITMAP OF LINE WRAPS 
TABMAP AND BITABL GET 
SWAPPED TO $0A60 WHEN SCREEN 
40/80 MODE IS CHANGED. 
LOGICAL FILE NUMBERS 
PRIMARY DEVICE NUMBERS 
SECONDARY ADDRESSES 



u 
u 



u 



u 



INDIRECT LOAD SUBROUTINE AREA 



INDSUB_RAMO 


039F 


927 


SHARED ROM FETCH SUB 


INDSUBJRAMl 


03AB 


939 


SHARED ROM FETCH SUB 


INDIN1_RAM1 


03B7 


950 


INDEXl INDIRECT FETCH 


INDIN2 


03C0 


959 


INDEX2 INDIRECT FETCH 


INDTXT 


03C9 


968 


TXTPTR 



I 

u 



n 
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MEMORY 
ADDRESS 
LABEL 



HEXADECIMAL DECIMAL 
ADDRESS ADDRESS 



DESCRimON 



INDIRECT LOAD SUBROUTINE AREA 



ZERO 


03D2 


977 


CURRENT- 


03D5 


979 


BANK 






TMPDES 


03D6 


980 


FIN RANK 


03DA 


984 


SAVSIZ 


03DB 


985 


BITS 


03DF 


989 


SPRTMP_1 


03E0 


990 


SPRTMP_2 


03E1 


991 


FG_BG 


03E2 


992 


FG_MC1 


03E3 


993 



VICSCN 



NUMERIC CONSTANT FOR BASIC 

CONTEXT FOR SYS,POKE,PEEK 

FROM BANK CMMD 

TEMP FOR INSTR 

BANK POINTER FOR STRING/ 

NUMBER CONVERT RTN 

TEMP WORK LOCATIONS FOR 

SSHAPE 

FAC#1 OVERFLOW DIGIT 

TEMP FOR SPRSAV 

PACKED FOREGROUND/ 
BACKGROUND COLOR NYBBLES 
PACKED FOREGROUND/ 
MULTICOLOR 1 COLOR NYBBLES 



PAGE FOUR & HIGHER DECLARATIONS 



0400 



(BEGINNING OF BANKABLE RAM) 
1024 VIDEO MATRIX #1: VIC 40-COLUMN 

TEXT SCREEN 

$0400-$07FF 
2048 BASIC RUN-TIME STACK (512 

BYTES) 

$0800-$09FF 



ABSOLUTE KERNAL VARIABLES 



n 



n 



SYSTEM-VECTOR 


OAOO 


2560 


DEJAVU 


0A02 


2562 


PALNTS 
INTT-STATUS 


0A03 
0A04 


2563 
2564 


MEMSTR 


0A05 


2565 


MEMSIZ 


0A07 


2567 


IRQTMP 


0A09 


2569 


CASTON 


OAOB 


2571 


KIKA26 
STUPID 
TIMOUT 
ENABL 


OAOC 
OAOD 
OAOE 
OAOF 


2572 
2573 
2574 
2575 



VECTOR TO RESTART SYSTEM 

(BASIC WARM) 

KERNAL WARM/COLD INIT'N 

STATUS BYTE 

PAL/NTSC SYSTEM FLAG 

FLAGS RESET VS. NMI STATUS 

FOR INIT'N RTNS 

PTR TO BOTTOM OF AVAIL. 

MEMORY IN SYSTEM BANK 

PTR TO TOP OF AVAILABLE 

MEMORY IN SYSTEM BANK 

TAPE HANDLER PRESERVES IRQ 

INDIRECT HERE 

TOD SENSE DURING TAPE 

OPERATIONS 

TAPE READ TEMPORARY 

TAPE READ DIIRQ INDICATOR 

FAST SERIAL TIMEOUT FLAG 

RS-232 ENABLES 
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C128 Memory Map (continued) 



MEMORY 
ADDRESS 
LABEL 



HEXADECIMAL DECIMAL 

ADDRESS ADDRESS DESCRIPTION 



ABSOLUTE KERNAL VARIABLES 



M51CTR 
M51CDR 
M51AJB 
RSSTAT 
BITNUM 
BAUDOF 


OAIO 
OAll 
0A12 
0A14 
0A15 
0A16 


2576 
2577 
2578 
2580 
2581 
2582 


RIDBE 


0A18 


2584 


RIDBS 


0A19 


2585 


RODBS 


OAIA 


2586 


RODBE 


OAIB 


2587 


SERIAL 


OAIC 


2588 


TIMER 


OAID 
GLOBAL ABSOLU'lE S 


2589 
iCREEr 


XMAX 

PAUSE 

RPTFLG 

KOUNT 

DELAY 


0A20 
0A21 
0A22 
0A23 
0A24 


2592 
2593 
2594 
2595 
2596 


LSTSHF 


0A25 


2597 


BLNON 


0A26 


2598 


BLNSW 
BLNCT 
GDBLN 


0A27 
0A28 
0A29 


2599 
2600 
2601 


GDCOL 
CURMOD 


0A2A 
0A2B 


2602 
2603 


VMl 


0A2C 


2604 


VM2 
VM3 
VM4 
LINTMP 


0A2D 
0A2E 
0A2F 
0A30 


2605 
2606 
2607 
2608 



RS-232 CONTROL REGISTER 

RS-232 COMMAND REGISTER 

RS-232 USER BAUD RATE 

RS-232 STATUS REGISTER 

RS-232 NUMBER OF BITS TO SEND 

RS-232 BAUD RATE FULL BIT TIME 

(CREATED BY OPEN) 

RS-232 INPUT BUFFER INDEX TO 

END 

RS-232 INPUT BUFFER INDEX TO 

START 

RS-232 OUTPUT BUFFER INDEX TO 

START 

RS-232 OUTPUT BUFFER INDEX TO 

END 

FAST SERIAL INTERNAL/EXTERNAL 

FLAG 

DECREMENTING JIFFIE REGISTER 



KEYBOARD QUEUE MAXIMUM SIZE 

<CTRL>S FLAG 

ENABLE KEY REPEATS 

DELAY BETWEEN KEY REPEATS 

DELAY BEFORE A KEY STARTS 

REPEATING 

DELAY BETWEEN <C«><SHFT> 

TOGGLES 

VIC CURSOR MODE (BLINKING, 

SOLID) 

VIC CURSOR DISABLE 

VIC CURSOR BLINK COUNTER 

VIC CURSOR CHARACTER BEFORE 

BLINK 

VIC CURSOR COLOR BEFORE BLINK 

VDC CURSOR MODE (WHEN 

ENABLED) 

VIC TEXT SCREEN/CHARACTER 

BASE POINTER 

VIC BIT-MAP BASE POINTER 

VDC TEXT SCREEN BASE 

VDC ATTRIBUTE BASE 

TEMPORARY POINTER TO LAST 

LINE FOR LOOP4 



u 



u 
u 



u 
u 



n 
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MEMORY 
ADDRESS 
LABEL 



HEXADECIMAL DECIMAL 
ADDRESS ADDRESS 



DESCRIPTION 



I i 



n 



1 1 



n 



GLOBAL ABSOLUTE SCREEN EDITOR DECLARATIONS 



SAV80A 


0A31 


2609 


SAV80B 


0A32 


2610 


CURCOL 


0A33 


2611 


SPLIT 


0A34 


2612 


FNADRX 


0A35 


2613 


PALCNT 


0A36 


2614 


SPEED 


0A37 


2615 


SPRITES 


0A38 


2616 


BLANKING 


0A39 


2617 


HOLD_OFF 


0A3A 


2618 


LDTB1_SA 


0A3B 


2619 


CLR_EA_LO 


0A3C 


2620 


CLR_EA_HI 


0A3D 


2621 




0A40 


2624 


XCNT 


0A80 


2688 


HULP 


OAAO 


2720 


FORMAT 


OAAA 


2730 


LENGTH 


OAAB 


2731 


MSAL 


OAAC 


2732 


SXREG 


OAAF 


2735 


SYREG 


OABO 


2736 


WRAP 


OABl 


2737 


XSAVE 


0AB2 


2738 


DIRECTION 


0AB3 


2739 


COUNT 


0AB4 


2740 


NUMBER 


0AB5 


2741 


SHIFT 


0AB6 


2742 


TEMPS 


0AB7 


2743 



TEMPORARY FOR 80-COL ROUTINES 

TEMPORARY FOR 80-COL ROUTINES 

VDC CURSOR COLOR BEFORE 

BLINK 

VIC SPLIT SCREEN RASTER VALUE 

SAVE .X DURING BANK 

OPERATIONS 

COUNTER FOR PAL SYSTEMS 

(JIFFIE ADJUSTMENT) 

SAVE SYSTEM SPEED DURING TAPE 

AND SERIAL OPS 

SAVE SPRITE ENABLES DURING 

TAPE AND SERIAL OPS 

SAVE BLANKING STATUS DURING 

TAPE OPS 

FLAG SET BY USER TO RESRV 

FULL CNTRL OF VIC 

HI BYTE: SA OF VIC SCRN (USE 

W/VMl TO MOVE SCRIV) 

8563 BLOCK FILL 

8563 BLOCK FILL 

$OA40-$OA7F RESERVED SWAP 

AREA FOR SCREEN VARIABLES 

WHEN (40/80) MODE CHANGES 

MONITOR'S DOMAIN 

COMPARE BUFFER (32 BYTES) 



ASM/DIS 

FOR ASSEMBLER 

1 BYTE TEMP USED ALL OVER 

1 BYTE TEMP USED ALL OVER 

1 BYTE TEMP FOR ASSEMBLER 

SAVE .X HERE DURING INDIRECT 

SUBROUTINE CALLS 

DIRECTION INDICATOR FOR 

•TRANSFER' 

PARSE NUMBER CONVERSION 

PARSE NUMBER CONVERSION 

PARSE NUMBER CONVERSION 



n 



CURBNK 



FUNCTION KEY ROM CARD TABLES 
OACO 2752 



CURRENT FUNCTION KEY ROM 
BANK BEING POLLED 
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u 



MEMORY 
ADDRESS 
LABEL 



HEXADECIMAL DECIMAL 

ADDRESS ADDRESS DESCRIPTION 



FUNCTION KEY ROM CARD TABLES 



PAT 


OACl 


2753 


DK_FLAG 


0AC5 


2757 




0AC6 


2758 


TBUFFR 


OBOO 


2810 



RS232I 


OCOO 


3072 


RS2320 


ODOO 


3328 




OEOO 


3584 


PKYBUF 


1000 


4096 


PKYDEF 


lOOA 


4106 



PHYSICAL ADDRESS TABLE(IDS OF 

LOGGED-IN CARDS) 

RESERVED FOR FOREIGN SCREEN 

EDITORS 

$0AC6-$0AFF RESERVED FOR 

SYSTEM 

CASSETTE BUFFER (192 BYTES) 

$0B00-$0BC0, THIS PAGE ALSO 

USED AS A BUFFER FOR THE DISK 

AUTO-BOOT 

RS-232 INPUT BUFFER 

RS-232 OUTPUT BUFFER 

SPRITE DEnNITION AREA (MUST 

BE BELOW $1000) 

$0E00-$0FFF, 512 BYTES 

PROGRAMMABLE FUNCTION KEY 

LENGTHS TABLE FOR 10 KEYS 

(F1-F8, <SHIFT RUN>, HELP) 

PROGRAMMABLE FUNCTION KEY 

STRINGS 



u 



kJ 



u 

u 



DOSSTR 

VWORK 

XYPOS 

XPOS 

YPOS 

XDEST 

YDEST 

XYABS 

XABS 

YABS 

XYSGN 

XSGN 

YSGN 

FCT 

ERRVAL 

LESSER 

GREATR 

ANGSGN 
SINVAL 





DOSA'SP AREA 


1100 


4352 


DOS OUTPUT STR. BUF 

48 BYTES TO BUILD DOS STRING 


1131 


4401 


GRAPHICS VARS 


1131 


4401 




1131 


4401 


CURRENT X POSITION 


1133 


4403 


CURRENT Y POSITION 


1135 


4405 


X-COORDINATE DESTINATION 


1137 


4407 


Y-COORDINATE DESTINATION 


1139 


4409 


LINE DRAWING VARIABLES 


1139 


4409 




113B 


4411 




113D 


4413 




113D 


4413 




113F 


4415 




1141 


4417 




1145 


4421 




1147 


4423 




1148 


4424 


ANGLE ROUTINE VARIABLES 


1149 


4425 


SIGN OF ANGLE 


114A 


4426 


SINE OF VALUE OF ANGLE 



u 
'J 



u 



r 

U 



n 
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n 



MEMORY 
ADDRESS 
LABEL 



COSVAL 
ANGCNT 



HEXADECIMAL 
ADDRESS 



DECIMAL 
ADDRESS 



DESCRIPTION 



DOSA^SP AREA 

114C 4428 COSINE OF VALUE OF ANGLE 

114E 4430 TEMPS FOR ANGLE DISTANCE 

ROUTINES 



BASIC GRAPHIC VARIABLES. 
THE FOLLOWING 24 BYTES ARE MULTIPLY DEFINED. 



XCIRCL 

YCIRCL 

XRADUS 

YRADUS 

ROTANG 

ANGBEG 

ANGEND 

XRCOS 

YRSIN 

XRSIN 

YRCOS 



1150 
1152 
1154 
1156 
1158 
115C 
115E 
1160 
1162 
1164 
1166 



CIRCLE DRAWING VARIABLES 

4432 CIRCLE CENTER, X COORDINATE 

4434 CIRCLE CENTER, Y COORDINATE 

4436 X RADIUS 

4438 Y RADIUS 

4440 ROTATION ANGLE 

4444 ARC ANGLE START 

4446 ARC ANGLE END 

4448 X RADIUS * COS(ROTATION ANGLE) 

4450 Y RADIUS * SIN(ROTATION ANGLE) 

4452 X RADIUS * SIN(ROTATION ANGLE) 

4454 Y RADIUS * COS(ROTATION ANGLE) 



BASIC GENERAL USE PARAMETERS 



XCENTR 

YCENTR 

XDISTl 

YDISTl 

XDIST2 

YDIST2 

DISEEND 

COLCNT 

ROWCNT 

STRCNT 

XCORDl 
YCORDl 
BOXANG 
XCOUNT 
YCOUNT 
BXLENG 
XCORD2 
YCORD2 



1150 
1152 
1154 
1156 
1158 
115A 
115C 
115E 
115F 
1160 

1150 
1152 
1154 
1156 
1158 
115A 
115C 
115E 



4432 
4434 
4436 
4438 
4440 
4442 
4444 
4446 
4447 
4448 

4432 
4434 
4436 
4438 
4440 
4442 
4444 
4446 



PLACEHOLDER 
CHAR'S COL. COUNTER 



BOX-DRAWING VARIABLES 
POINT 1 X-COORD. 
POINT 1 Y-COORD. 
ROTATION ANGLE 



LENGTH OF A SIDE 



KEYLEN 
KEYNXT 
STRSZ 



SHAPE AND MOVE-SHAPE VARIABLES 

1151 4433 

1152 4434 

1153 4435 STRING LEN 
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C128 Memory Map (continued) 



MEMORY 
ADDRESS 
LABEL 



HEXADECIMAL DECIMAL 

ADDRESS ADDRESS DESCRIPTION 



SHAPE AND MOVE-SHAPE VARIABLES 



GETTYP 


1154 


4436 


STRPTR 


1155 


4437 


OLDBYT 


1156 


4438 


NEWBYT 


1157 


4439 




1158 


4440 


XSIZE 


1159 


4441 


YSIZE 


115B 


4443 


XSAVE 


115D 


4445 


STRADR 


115F 


4447 


BITIDX 


1161 


4449 



REPLACE SHAPE MODE 

STRING POS'N COUNTER 

OLD BIT MAP BYTE 

NEW STRING OR BIT MAP BYTE 

PLACEHOLDER 

SHAPE COLUMN LENGTH 

SHAPE ROW LENGTH 

TEMP FOR COLUMN LENGTH 

SAVE SHAPE STRING DESCRIPTOR 

BIT INDEX INTO BYTE 



u 



\ i 



) i 



BASIC GRAPHIC VARIABLES 



CHRPAG 


1168 


BITCNT 


1169 


SCALEM 


116A 


WIDTH 


116B 


FILFLG 


116C 


BITMSK 


116D 


NUMCNT 


116E 


TRCFLG 


116F 


RENUM_TMP_1 


1170 


RENUM_TMP_2 


1172 


T3 


1174 


T4 


1175 


VTEMP3 


1177 


VTEMP4 


1178 


VTEMP5 


1179 


ADRAYl 


117A 


ADRAY2 


117C 


SPRITE DATA 


117E 


VIC_SAVE 


11D6 


UPPER LOWER 


llEB 


UPPER-GRAPHIC 


llEC 


DOSSA 


llED 



4456 

4457 
4458 
4459 
4460 
4461 
4462 
4463 
4464 
4466 
4468 
4469 
4471 
4472 
4473 
4474 

4476 

4478 

4566 

4587 

4588 
4589 



HIGH BYTE: ADDR OF CHARROM 

FOR 'CHAR' CMD. 

TEMP FOR GSHAPE 

SCALE MODE FLAG 

DOUBLE WIDTH FLAG 

BOX FILL FLAG 

TEMP FOR BIT MASK 

FLAGS TRACE MODE 
A TEMP FOR RENUMBER 
A TEMP FOR RENUMBER 



GRAPHIC TEMP STORAGE 



PTR TO ROUTINE: CONVERT 

FLOAT -^ INTEGER 

PTR TO ROUTINE: CONVERT 

INTEGER -^ FLOAT 

SPRITE SPEED/DIRECTION TABLES 

($117E-D5) 

COPY OF VIC REG'S, USED TO 

UPDATE CHIP DURING RETRACE 

(21 BYTES, $11D6-EA) 

POINTER TO UPPER/LOWER CHAR 

SET FOR CHAR 

PTR. TO UPPER/GRAPHIC CHAR. SET 

TEMP STORAGE FOR FILE SA 

DURING RECORD CMD 



u 



u 

L 






n 
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I 1 
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MEMORY 
ADDRESS 
LABEL 



OLDLIN 
OLDTXT 



HEXADECIMAL DECIMAL 

ADDRESS ADDRESS DESCRIPTION 



BASIC GENERAL NON-ZP STORAGE 



1200 
1202 



4608 PREVIOUS BASIC LINE NUMBER 

4610 POINTER: BASIC STATEMENT FOR 

CONTINUE 



PRINT USING DECLARATIONS 



n 



PUCHRS 


1204 


4612 


PUFELL 


1204 


4612 


PUCOMA 


1205 


4613 


PUDOT 


1206 


4614 


PUMONY 


1207 


4615 


ERRNUM 


1208 


4616 


ERRLIN 


1209 


4617 


TRAPNO 


120B 


4619 


TMPTRP 


120D 


4621 


ERRTXT 


120E 


4622 


TEXT_TOP 


1210 


4624 


MAX_MEM_0 


1212 


4626 


TMPTXT 


1214 


4628 


TMPLIN 


1216 


4630 


USRPOK 


1218 


4632 


RNDX 


121B 


4635 


CIRCLE-SEGMENT 


1220 


4640 


DEJAVU 


1221 


4641 



PRINT USING FILL SYMBOL 

PRINT USING COMMA SYMBOL 

PRINT USING D.P. SYMBOL 

PRINT USING MONETARY SYMBOL 

USED BY ERROR TRAPPING 

ROUTINE-LAST ERR NO 

LINE # OF LAST ERROR— $FFFF IF 

NO ERROR 

LINE TO GO TO ON ERROR. $FFXX 

IF NONE SET 

HOLD TRAP # TEMPOR. 

TOP OF TEXT POINTER 
HIGHEST ADDRESS AVAILABLE 
TO BASIC IN RAM 
USED BY DO-LOOP. COULD BE 
MULT. ASSIGNED 



DEGREES PER CIRCLE SEGMENT 
'COLD' OR 'WARM' RESET STATUS 



BASIC STORAGE FOR MUSIC VECTORS 



I ! 



TEMPO_RATE 


1222 


4642 


VOICES 


1223 


4643 


NTIME 


1229 


4649 


OCTAVE 


122B 


4651 


SHARP 


122C 


4652 


PITCH 


122D 


4653 


VOICE 


122F 


4655 


WAVEO 


1230 


4656 


DNOTE 


1233 


4659 


FLTSAV 


1234 


4660 


FLTFLG 


1238 


4664 


NIBBLE 


1239 


4665 


TONNUM 


123A 


4666 
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C128 Memory Map (continued) 



MEMORY 
ADDRESS 
LABEL 



HEXADECIMAL DECIMAL 
ADDRESS ADDRESS 



DESCRIPTION 



u 





BASIC STORAGE FOR MUSIC VECTORS 



TONVAL 


123B 


4667 


PARCNT 


123E 


4668 


ATKTAB 


123F 


4669 


SUSTAB 


1249 


4681 


WAVTAB 


1253 


4691 


PULSLW 


125D 


4701 


PULSHI 


1267 


4711 


lilLTERS 


1271 


4721 


INT_TRIP_FLAG 


IN 
1276 


TERRUPT 
4726 


INT-ADR I-O 


1279 


4729 


INT_ADR_HI 


127C 


4732 


INTVAL 


127F 


4735 


COLTYP 


1280 


4736 




BASIC SOUND C( 


SOUND-VOICE 


1281 


4737 


SOUND TIME I,0 


1282 


4738 


SOUND TIME, HI 


1285 


4741 


SOUND_MAX_LO 


1288 


4744 


SOUND_MAX_HI 


128B 


4747 


SOUND_MIN_LO 


128E 


4750 


SOUND_MIN_HI 


1291 


4753 


SOUND JDIRECTION 


1294 


4756 


SOUND_STEP_LO 


1297 


4759 


SOUND_STEP_HI 


129A 


4762 


SOUND_FREQ_LO 


129D 


4765 


SOUND JREQ-HI 


12A0 


4768 


TEMP TIME 1,0 


12A3 


4771 


TEMP TIME HI 


12A4 


4772 


TEMP_MAX 1,0 


12A5 


4773 


TEMP_MAX HI 


12A6 


4774 


TEMP_MIN_LO 


12A7 


4775 


TEMP_MIN_HI 


12A8 


4776 


TEMP_DIRECTION 


12A9 


4777 


TEMP_STEP_LO 


12AA 


4778 


TEMP_STEP_HI 


12AB 


4779 


TEMP_EREQ_LO 


12AC 


4780 


TEMP_rREQ_HI 


12AD 


4781 


TEMP_PULSE_LO 


12AE 


4782 


TEMP_PULSE_HI 


12AF 


4783 


TEMP_WAVEFORM 


12B0 


4784 



u 




u 
u 

11 

u 
u 
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1 


MEMORY 








^■M 


ADDRESS 


HEXADECIMAL 


DECIMAL 






LABEL 


ADDRESS 


ADDRESS 


DESCRIPTION 






BASIC SOUND COMMAND VARS 


r^ 


POT_TEMP_l 


12B1 


4785 


TEMPORARIES FOR 'POT' 
FUNCTION 


i , 


POT_tEMP_2 


12B2 


4786 






WINDOW_TEMP 


12B3 


4787 




/— 


SAVRAM 


12B7 


4791 


USED BY SPRDEF & SAVSPR 


i 1 


DEFMOD 


12FA 


4858 


USED BY SPRDEF & SAVSPR 


' t 


LINCNT 


12FB 


4859 


USED BY SPRDEF & SAVSPR 




SPRITE_NUMBER 


12FC 


4860 


USED BY SPRDEF & SAVSPR 




IRQ_WRAP_FLAG 


12FD 


4861 


USED BY BASIC IRQ TO BLOCK 
ALL BUT ONE IRQ CALL 






1300 


4864 


APPLICATION PROGRAM AREA 
$1300-$1BFF 


"1 


RAMBOT 


ICOO 


7168 


START OF BASIC TEXT $1C00- 
$EFFF rKRRNAI. SETS MPlMRnT 



ICOO 



2000 



HERE) 
OR 
7168 VIDEO MATRIX #2 (1KB OF 

COLORS FOR BITMAP, IF 
ALLOCATED) $1C00-$1FFF 

8192 VIC BITMAP (8KB, IF ALLOCATED) 

$2000-$3FFF 



BEGINNING OF ROM OVER RAM 

4000 16384 C128 BASIC LO ROM 

START OF BASIC TEXT IF BIT MAP 
IS ALLOCATED (RAM) 
$4000-$EFFF 



8000 



32768 



C128 BASIC HI ROM (OR FUNCTION 
ROM) $800&-$BFFF 



BASIC JUMP TABLE 



MEMORY 
ADDRESS 
LABEL 



HEXADECIMAL DECIMAL 
ADDRESS ADDRESS 



DESCRIPTION 



JMP HARD_RESET 4000 
JMP SOFT_RESET 4003 
JMP BASIC_IRQ 4006 



BASIC ENTRY 

16384 COLD ENTRY 

16387 WARM ENTRY 

16390 IRQ ENTRY 



JMP AYINT 
JMP GIVAYF 



FORMAT CONVERSIONS 

AFOO 44800 CONVERT F.P. TO INTEGER 

AF03 44803 CONVERT INTEGER TO F.P. 











— 
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Basic Jump Table (continued) 








MEMORY 








- 


ADDRESS 


HEXADECIMAL DECIMAL 






LABEL 


ADDRESS 


ADDRESS 


DESCRIFI'ION 


^ 




] 


FORMAT CONVERSIONS 




JMPFOUT 
JMP VAL_1 


AF06 


44806 


CONVERT F.P. TO ASCH STRING 




AF09 


44809 


CONVERT ASCn STRING TO P.P. 


I—/ 


IMP GETADR 


AFOC 


44812 


CONVERT F.P. TO AN ADDRESS 




JMP FLOATC 


AFOF 


44815 


CONVERT ADDRESS TO F.P. 


' 






MATH FUNCTIONS 


i—j 


JMPFSUB 


AF12 


44818 


MEM - FACC 


-- 


JMPFSUBT 


AF15 


44821 


ARG - FACC 




JMPFADD 


AF18 


44824 


MEM + FACC 


wJ 


JMPFADDT 


AFIB 


44827 


ARG - FACC 




JMP FMULT 


AFIE 


44830 


MEM * FACC 


) 




JMPFMULTT 


AF21 


44833 


ARG * FACC 


! 




JMPFDIV 


AF24 


44836 


MEM / FACC 


o 


JMPFDFVT 


AF27 


44839 


ARG / FACC 




JMP LOG 


AF2A 


44842 


COMPUTE NATURAL LOG OF FACC 


'"( 


JMP INT 


AF2D 


44845 


PERFORM BASIC INT ON FACC 


JMPSQR 


AF30 


44848 


COMPUTE SQUARE ROOT OF FACC 


JMP NEGOP 


AF33 


44851 


NEGATE FACC 




JMPFPWR 


AF36 


44854 


RAISE ARG TO THE MEM POWER 


i 


JMP FPWRT 


AF39 


44857 


RAISE ARG TO THE FACC POWER 






JMP EXP 


AF3C 


44860 


COMPUTE EXP OF FACC 


-1 


JMP COS 


AF3F 


44863 


COMPUTE COS OF FACC 




JMP SIN 


AF42 


44866 


COMPUTE SIN OF FACC 


u- 


JMP TAN 


AF45 


44869 


COMPUTE TAN OF FACC 


JMPATN 


AF48 


44872 


COMPUTE ATN OF FACC 


JMP ROUND 


AF4B 


44875 


ROUND FACC 




JMPABS 


AF4E 


44878 


ABSOLUTE VALUE OF FACC 


1 


JMP SIGN 


AF51 


44881 


TEST SIGN OF FACC 


JMPFCOMP 


AF54 


dJSOtd 


COMPARE FACC WITH MEM 




JMPRNDO 


AF57 


44887 


GENERATE RANDOM F.P. NUMBER 


] 






MOVEMENT 


JMP CONUPK 


AF5A 


44890 


MOVE RAM MEM TO ARG 




JMP ROMUPK 


AF5D 


44893 


MOVE ROM MEM TO ARG 


r 


JMPMOVFRM 


AF60 


44896 


MOVE RAM MEM TO FACC 


1 


JMP MOVFM 


AF63 


44899 


MOVE ROM MEM TO FACC 


i-j 


JMPMOVMF 


AF66 


44902 


MOVE FACC TO MEM 




JMP MOVFA 


AF69 


44905 


MOVE ARG TO FACC 


1 


JMP MOVAF 


AF6C 


44908 


MOVE FACC TO ARG 


1 






OTHER BASIC ROU IINES 




JMPOPTAB 


AFdF 


44911 




L 




JMP DRAWLN 


AF72 


44914 







u 



n 
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n 

n 



n 



MEMORY 
ADDRESS 
LABEL 



HEXADECIMAL DECIMAL 

ADDRESS ADDRESS DESCRIPTION 



JMP GPLOT 


AF75 


JMPCIRSUB 


AF78 


JMP RUN 


AF7B 


JMPRUNC 


AF7E 


JMP CLEAR 


AFSl 


JMP NEW 


AF84 


JMP LNKPRG 


AF87 


JMP CRUNCH 


AF8A 


JMP FNDLIN 


AF8D 


JMP NEWSTT 


AF90 


JMPEVAL 


AF93 


JMPFRMEVL 


AF9d 


JMP RUN_A_ 




PROGRAM 


AF99 


JMP SETEXC 


AF9C 


JMP LINGET 


AF9F 


JMP GARBA2 


AFA2 


JMP EXECUTE_A_ 




LINE 


AFA5 


JMP CALL 


BOOO 


JMP BREAK 


B003 


JMP MONCMD 


B006 



OTHER BASIC ROUTINES 

44917 
44920 
44923 
44926 
44929 
44932 
44935 
44938 
44941 
44944 
44947 
44950 

44953 
44956 
44959 
44962 

44965 



MONITOR ENTRY 



COOO 



45056 MONITOR CALL ENTRY 

45059 MONITOR BREAK ENTRY 

45062 MONITOR COMMAND PARSER 

ENTRY 
49152 KERNAL (OR FUNCTION) ROM 

$COOO-$FFFF 



EDITOR JUMP TABLE 



MEMORY 








ADDRESS 


HEXADECIMAL 


DECIMAL 




LABEL 


ADDRESS 


ADDRESS 


DESCRIPTION 


JMPCINT 


COOO 


49152 


INITULIZE EDITOR & SCREEN 


JMP DISPLY 


C003 


49155 


DISPLAY CHARAC IN .A, COLOR 
IN.X 


JMPLP2 


C006 


49158 


GET KEY FROM IRQ BUFFER 
INTO .A 


JMP LOOP5 


C009 


49161 


GET A CHR FROM SCRN LINE 
INTO.A 


JMP PRINT 


COOC 


49164 


PRINT CHARACTER IN .A 


JMP SCRORG 


COOF 


49167 


GET # OF SCRN ROWS, COLS 
INTOX&Y 
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Editor Jump Table (continued) 



u 



MEMORY 
ADDRESS 
LABEL 



HEXADECIMAL DECIMAL 

ADDRESS ADDRESS DESCRIFHON 



JMP SCNKEY 
JMP REPEAT 


C012 
C015 


49170 
49173 


JMP PLOT 


C018 


49176 


JMP CURSOR 
JMP ESCAPE 


COIB 
COIE 


49179 
49182 


JMP KEYSET 


C021 


49185 


JMP IRQ 
JMPINIT80 


C024 
C027 


49188 
49191 


JMP SWAPPER 


C02A 


49194 


JMP WINDOW 


C02D 


49197 




DOOO 


53248 



VICREGO 

VICREGl 

VICREG2 

VICREG3 

VICREG4 

VICREG5 

VICREG6 

VICREG7 

VICREG8 

VICREG9 

VICREGIO 

VICREGll 

VICREG12 

VICREG13 

VICREG14 

VICREG15 

VICREG16 



SCAN KEYBOARD SUBROUTINE 

HANDLE REPEAT KEY&STORE 

DECODED KEY 

READ OR SET CRSR POSITION IN 

.X, .Y 

MOVE 8563 CURSOR SUBROUTINE 

EXECUTE ESC FUNCTION USING 

CHR IN .A 

REDEFINE A PROGRAMMABLE 

FUNC'N KEY 

IRQ ENTRY 

INITIALIZE 80-COLUMN 

CHARACTER SET 

SWAP EDITOR LOCALS (40/80 

CHANGE) 

SET TOP-LEFT OR BOT-RIGHT OF 

WINDOW 

VIC CHARACTER ROM 

($DOOO-$DFFF) 



ii 



VIC CHIP REGISTERS 



DOOO 
DOOl 
D002 
D003 
D004 
D005 
D006 
D007 
D008 
D009 
DOOA 
DOOB 
DOOC 
DOOD 
DOOE 
DOOF 
DOlO 



53248 
53249 
53250 
53251 
53252 
53253 
53254 
53255 
53256 
53257 
53258 
53259 
53260 
53261 
53262 
53263 
53264 



SPRITE 0, X- 
SPRITE 0, Y 
SPRITE 1, X. 
SPRITE 1, Y 
SPRITE 2, X 
SPRUE 2, Y 
SPRITE 3, X 
SPRUE 3, Y 
SPRUE 4, X- 
SPRITE 4, Y- 
SPRITE 5, X- 
SPRITE 5, Y- 
SPRITE 6, X- 
SPRUE 6, Y- 
SPRITE 7, X- 
SPRITE 7, Y- 
MSBIT OF X 
SPRITES 0-7 



LOCATION 
LOCATION 
LOCATION 
LOCATION 
LOCATION 
LOCATION 
LOCATION 
LOCATION 
LOCATION 
LOCATION 
LOCATION 
LOCATION 
LOCATION 
LOCATION 
LOCATION 
LOCATION 
LOCATION FOR 







\ 







u 



u 



n 
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1 1 



MEMORY 
ADDRESS 
LABEL 



HEXADECIMAL DECIMAL 
ADDRESS ADDRESS 



DESCRIPTION 



VICREG17 



DOll 



VIC CHIP REGISTERS 

53265 VIC CONTROL REGISTER 1 



j i 

^^ 
! i 
1 i 








n 
1 

1 


VICREG18 


D012 


53266 




VICREG19 


D013 


53267 


n 


VICREG20 


D014 


53268 


ii 


VICREG21 


D015 


53269 




VICREG22 


D016 


53270 



VICREG23 
VICREG24 



D017 
D018 



53271 
53272 



5 

4 



2-0 



7 RASTER COMPARE BIT 
6 EXTENDED COLOR TEXT 

MODE (1 = ON) 

BIT MAP MODE (1 =ENABLE) 

BLANK SCREEN TO BORDER 

CLR (0 = BLANK) 

SELECT 24/25 ROW TEXT 

DISPLAY (1 = 25) 

SMOOTH SCROLL TO Y 

DOT POSITION 
READAVRITE RASTER VALUE FOR 
COMPARE IRQ 

LIGHT PEN LATCH X-POSITION 
LIGHT PEN LATCH Y-POSITION 
SPRITES 0-7 DISPLAY ENABLE 
(1 = ENABLE) 

VIC CONTROL REGISTER 2 
BITS 



7-6 UNUSED 
5 RESET 
4 MULTI-COLOR MODE 

(1 = ENABLE) 
3 SELECT 38/40 COLUMN 
DISPLAY (1 = 40 COLS) 
2-0 SMOOTH SCROLL TO 
' X-POSITION 

SPRITES 0-7 Y EXPAND 

VIC MEMORY CONTROL REGISTER 

BITS ($D018) 



7-4 
3-0 



VIDEO MATRIX BASE 
ADDRESS 

CHARACTER DOT-DATA 
BASE ADDRESS 



! ! 
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C128 Memory Map (continued) 



MEMORY 
ADDRESS 
LABEL 



VICREG25 



VICREG26 



HEXADECIMAL 
ADDRESS 



DECIMAL 
ADDRESS 



DESCRIFnON 



VIC CHIP REGISTERS 



D019 



53273 



DOIA 



VICREG27 


DOIB 


53275 


VICREG28 


DOIC 


53276 


VICREG29 


DOID 


53277 


VICREG30 


DOIE 


53278 


VICREG31 


DOIF 


53279 


VICREG32 


D020 


53280 


VICREG33 


D021 


53281 


VICREG34 


D022 


53282 


VICREG35 


D023 


53283 


VICREG36 


D024 


53284 


VICREG37 


D025 


53285 


VICREG38 


D026 


53286 


VICREG39 


D027 


53287 


VICREG40 


D028 


53288 


VICREG41 


D029 


53289 


VICREG42 


D02A 


53290 



VIC INTERRUPT FLAG REGISTER 
(1= IRQ OCCURRED) 



6-4 
3 

2 

1 





SET ON ANY ENABLED VIC 

IRQ CONDITION 

NOT USED 

LIGHT PEN TRIGGERED 

IRQ FLAG 

SPRITE TO SPRITE 

COLLISION IRQ FLAG 

SPRITE TO BACKGROUND 

COLLISION IRQ FLAG 

RASTER COMPARE IRQ 

FLAG 



53274 IRQ ENABLE (1 = ENABLED) BITS 



7-4 
3 
2 
1 




NOT USED 
LIGHT PEN 
SPRITE TO SPRITE 
SPRITE TO BACKGROUND 
IRQ 



SPRITES 0-7 BACKGROUND 

PRIORITY (1 = SPRITE) 

SPRITES 0-7 MULTI-COLOR MODE 

(1 = MULTI-COLOR) 

SPRITES 0-7 X EXPAND 

SPRITE TO SPRITE COLLISION 

LATCH 

SPRITE TO BACKGROUND 

COLLISION LATCH 

BORDER COLOR 

BACKGROUND COLOR 

BACKGROUND COLOR 1 

BACKGROUND COLOR 2 

BACKGROUND COLOR 3 

SPRITE MULTI-COLOR REGISTER 

SPRITE MULTI-COLOR REGISTER 1 

SPRITE COLOR 

SPRITE 1 COLOR 

SPRITE 2 COLOR 

SPRITE 3 COLOR 



u 



\ \ 



u 



u 



u 



i / 



>J 



U 



n 
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MEMORY 

ADDRESS 
LABEL 



HEXADECIMAL DECIMAL 

ADDRESS ADDRESS DESCRIPTION 



VIC CHIP REGISTERS 



VICREG43 
VICREG44 
VICREG45 
VICREG46 
VICREG47 



VICREG48 



SIDREGO 
SIDREGl 
SIDREG2 
SIDREG3 
SIDREG4 



SIDREG5 



D02B 


53291 


SPRITE 4 COLOR 


D02C 


53292 


SPRITE 5 COLOR 


D02D 


53293 


SPRITE 6 COLOR 


D02E 


53294 


SPRITE 7 COLOR 


D02F 


53295 


KEYBOARD LINES 






BITS 






7-3 


NOT USED 




53296 


2-0 


K2, Kl AND KO 


D030 


CLOCK SPEED 






BTTS 






7-2 


NOT USED 






1 


TEST 




Sm REGISTE 





2 MHZ 




RS 




D400 


54272 


VOIC 


E 1 FREQUENCY LO 


D401 


54273 


VOICE 1 FREQUENCY HI 


D402 


54274 


VOICE 1 PULSE WIDTH LO 


D403 


54275 


VOICE 1 PULSE WIDTH HI (0-15) 


D404 


5427(> 


VOICE 1 CONTROL REGISTER 




7 


NOISE (1 = NOISE) 






6 


PULSE (1 = PULSE) 






5 


SAW (1 = SAWTOOTH) 






4 


TRI (1 = TRIANGLE) 






3 


TEST (1 = DISABLE 

OSCILLATOR) 






2 


RING (1= RING MODULATE 
OSC 1 WITH OSC 
3 OUTPUT) 






1 


SYNC (1 = SYNCHRONIZE 
OSC 1 WUH OSC 
3FREQ) 









GATE (1 = START ATTACK/ 








DECAY/SUSTAIN 








0= START RELEASE) 


D405 


54277 


VOIC 


E 1 AITACK/DECAY 




7--I 


ATTACK (0-15) 






3-0 


DECAY (0-15) 
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C128 Memory Map (continued) 



MEMORY 
ADDRESS 
tABEL 



HEXADECIMAL DECIMAL 
ADDRESS ADDRESS 



DESCRIPTION 



SIDREG6 



SIDREG7 

SIDREG8 

SroREG9 

SIDREGIO 

SIDREGll 



D406 



D407 
D408 
D409 
D40A 
D40B 



SID REGISTERS 

54278 VOICE 1 SUSTAIN/RELEASE 



SIDREG12 



SIDREG13 



SIDREG14 
SIDREG15 
SIDREG16 
SIDREG17 



D40C 



D40D 



D40E 
D40F 
D410 
D411 





7-4 


SUSTAIN (0-15) 




J-0 


RELEASE (0-15) 


54279 


VOICE 2 FREQUENCY LO 


54280 


VOICE 2 FREQUENCY HI 


54281 


VOICE 2 PULSE WIDTH LO 


54282 


VOICE 2 PULSE WIDTH HI (0-15) 


54283 


VOICE 2 CONTROL REGISTER 




7 


NOISE (1 = NOISE) 




6 


PULSE (1 = PULSE) 




5 


SAW (1 = SAWTOOTH) 




4 


TRI (1 = TRIANGLE) 




3 


TEST (1 = DISABLE 

OSCILLATOR) 




2 


RING (1= RING MODULATE 
OSC 2 WITH OSC 
1 OUIPUT) 




1 


SYNC (1= SYNCHRONIZE 
OSC 2 WITH OSC 
IFREQ) 







GATE (1 = START ATTACK/ 






DECAY/SUSTAIN 






0= START RELEASE) 


54284 


VOICE 2 ATTACK/DECAY 




7-4 


ATTACK (0-15) 




3-0 


DECAY (0-15) 


54285 


VOIC 


E 2 SUSTAIN/RELEASE 




7-4 


SUSTAIN (0-15) 




3-0 


RELEASE (0-15) 



54286 VOICE 3 FREQUENCY LO 

54287 VOICE 3 FREQUENCY HI 

54288 VOICE 3 PULSE WIDTH LO 

54289 VOICE 3 PULSE WIDTH HI (0-15) 



*~' 



\ I 

u 
u 



b 



u 



u 



U 
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MEMORY 
ADDRESS 
LABEL 



HEXADECIMAL DECIMAL 
ADDRESS ADDRESS 



DESCRIPTION 



SIDREG18 



D412 



Sm REGISTERS 

54290 VOICE 3 CONTROL REGISTER 



SIDREG19 



SIDREG20 



SIDREG21 
SIDREG22 
SIDREG23 



D413 



D414 



D415 
D416 
D417 



I I 





7 


NOISE (1= NOISE) 




6 


PULSE (1 = PULSE) 




5 


SAW (1 = SAWTOOTH) 




4 


TRI (1 = TRIANGLE) 




3 


TEST (1 = DISABLE 

OSCILLATOR) 




2 


RING (1= RING MODULATE 
OSC 3 WITH OSC 
2 OUTPUT) 




1 


SYNC (1 = SYNCHRONIZE 
OSC 3 WITH OSC 
2FREQ) 







GATE (1 = START ATTACK/ 






DECAY/SUSTAIN 






0= START RELEASE) 


54291 


VOICE 3 ATTACK/DECAY 




7-4 


ATTACK (0-15) 




3-0 


DECAY (0-15) 


54292 


VOICE 3 SUSTAIN/RELEASE 




7-4 


SUSTAIN (0-15) 




3-0 


RELEASE (0-15) 


54293 


FILTER CUTOFF FREQUENCY LO 


54294 


FILTER CUTOFF FREQUENCY HI 


54295 


RESONANCE/FILTER 




7-4 


FILTER RESONANCE (0-15) 




3 


FILTER EXTERNAL INPUT 

(1=YES) 




2 


FILTER VOICE 3 OUTPUT 

(1 = YES) 




1 


FILTER VOICE 2 OUTPUT 

(1 = YES) 







FILTER VOICE 1 OUTPUT 






(1 = YES) 
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C128 Memory Map (continued) 



MEMORY 
ADDRESS 
LABEL 



HEXADECIMAL DECIMAL 
ADDRESS ADDRESS 



DESCRIPTION 



SIDREG24 



D418 



SID REGISTERS 

54296 MODEA^OLUME 



7 


CUTOFF VOICE 3 OUTPUT 




(l = OFF) 


6 


SELECT HI-PASS FILTER 




(l = ON) 


5 


SELECT BAND-PASS FILTER 




(l = ON) 


4 


SELECT LO-PASS FILTER 




(l = ON) 


3-0 


OUTPUT VOLUME (0-15) 



SIDREG25 
SIDREG26 
SIDREG27 

SIDREG28 



D419 
D41A 
D41B 

D41C 



54297 
54298 
54299 

54300 



POT X, A/D CONVERTER, PADDLE 1 

POT Y, A/D CONVERTER, PADDLE 2 

OSCILLATOR 3, RANDOM NUMBER 

GENERATOR 

ENVELOPE GENERATOR 3 OUTPUT 



C128 MEMORY MANAGEMENT UNIT, PRIMARY REGISTERS 
IMPLEMENTS C128, C64, & CP/M 3.0 MODES 



MMUCRl 


D500 


54528 


CONFIGURATION REGISTER 


PCRA 


D501 


54529 


PRECONFIGURATION REGISTER A 


PCRB 


D502 


54530 


PRECONFIGURATION REGISTER B 


PCRC 


D503 


54531 


PRECONFIGURATION REGISTER C 


PCRD 


D504 


54532 


PRECONFIGURATION REGISTER D 
BITS ($D500-$D504) 




7-6 


RAM BANK (0-3) 








5-4 


ROM HI (SYSTEM, INT, 
EXT, RAM) 








3-2 


ROM MID (SYSTEM, INT, 
EXT, RAM) 








1 


ROM LO (SYSTEM, RAM) 











1/0 (I/O BLOCK, 




D505 


54533 




ELSE ROM-HI) 


MMUMCR 


MOD] 


E CONFIGURATION REGISTER 




7 


40/80 KEY SENSE 








6 


OS MODE, = C128/1 = C64 








5 


/EXROM LINE SENSE 








4 


/GAME LINE SENSE 








3 


FSDIR 








2-1 


NOT USED 











PROCESSOR, = Z80/1 = 8502 



y 



u 
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i_J 
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MEMORY 
ADDRESS 
LABEL 



HEXADECIMAL DECIMAL 
ADDRESS ADDRESS 



DESCRIPTION 



C128 MEMORY MANAGEMENT UNIT, PRIMARY REGISTERS 
IMPLEMENTS C128, C64, & CP/M 3.0 MODES 



MMURCR 



MMUVER 



D506 



O50B 



54534 



54539 



RAM CONFIGURATION REGISTER 



7-6 
5-4 
3-2 
1-0 



VIC RAM BANK (VA17 & 

VA16) 

RAM BLOCK (FOR FUTURE 

EXPANSION) 

RAM SHARE STATUS (NONE, 

BOT, TOP, BOTH) 

RAM SHARE AMOUNT (IK, 

4K, 8K, 16K) 



MMUPOL 


D507 


54535 


PAGED 
POINTER LOW 


MMUPOH 


D508 


54536 


PAGEO 
POINTER HIGH 


MMUPIL 


D509 


54537 


PAGE! 
POINTER LOW 


MMUPIH 


D50A 


54538 


PAGEl 
POINTER HIGH 



SWAPS PAGEO 
AND/OR PAGEl 
WITH ANY 
OTHER PAGE IN 
THE 256K 
ADDRESS SPACE 



BITS ($D508 & $D50A) 



7-4 
3-2 

1-0 



A19-A18 (USED IN 1MB 

SYSTEM) 
A17-A16 (256K SYSTEM) 



BITS ($D507 & $D509) 



7-0 A15-A8 



MMU VERSION NUMBER 



7-4 
3-0 



BANK VERSION 
MMU VERSION 



VDCADR 



C128 80-COLUMN VIDEO DISPLAY CONTROLLER 

D600 54784 8563 ADDRESS REGISTER 
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C128 Memory Map (continued) 



MEMORY 
ADDRESS 
LABEL 



HEXADECIMAL DECIMAL 
ADDRESS ADDRESS 



DESCRIPTION 



ADDRESS AND DATA REGISTER BITS 
7 6 5 4 3 2 10 



D600 ^WRITE 


— 


— 


R5 R4 R3 R2 Rl 


RO 


READ 


STATUS 


LP 


VBLANK — _ — _ 


— 


VDCDAT 


D601 




54785 8563 DATA REGISTER 




D601 DATA 


D7 


D6 


D5 D4 D3 D2 Dl 


DO 



Ll 



ii 



ADDITIONAL 8563 REGISTERS ARE NOT VISIBLE TO THE 8502 

D700 55040 RESERVED I/O BLOCK 

VICCOL D800 55296 VIC COLOR MATRIX, 1 KB 

($D800-$DBFF) 



6526 CIA#1, COMPLEX INTERFACE ADAPTER #1 
KEYBOARD, JOYSTICK, PADDLES, LIGHTPEN, FAST DISK 



DIPRA 
BITS ($DCOO) 






PRAO 


1 


PRAl 


2 


PRA2 


3 


PRA3 


4 


PRA4 


5 


PRA5 


6 


PRA6 


7 


PRA7 


DIPR] 


B 


BITS 


($DC01) 





PRBO 


1 


PRBl 


2 


PRB2 


3 


PRB3 


4 


PRB4 


5 


PRB5 


6 


PRB6 


7 


PRB7 



DIDDRA 
DIDDRB 
DITIL 



DCOO 56320 PORT A (OUTPUT KEYBOARD 

COLUMNS) 



KEYBD 0/P CO/JOY #1 DIRECTION 

KEYBD 0/P Cl/JOY #1 DIRECTION 

KEYBD O/P C2/JOY #1 DIRECTION/PADDLE FIRE BUTTON 

KEYBD O/P C3/JOY #1 DIRECTION/PADDLE FIRE BUTTON 

KEYBD O/P C4/JOY #1 FIRE BUTTON 

KEYBD 0/P C5/ 

KEYBD O/P C6/ /SELECT PORT #1 PADDLES 

KEYBD 0/P C7/ /SELECT PORT #2 PADDLES 



DCOl 



56321 



PORT B (INPUT KEYBOARD ROWS) 



KEYBD I/P RO/JOY #2 DIRECTION 

KEYBD I/P Rl/JOY #2 DIRECTION/PADDLE FIRE BUTTON 

KEYBD I/P R2/JOY #2 DIRECTION/PADDLE FIRE BUTTON 

KEYBD I/P R3/JOY #2 DIRECTION/ 

KEYBD I/P R4/JOY #2 FIRE BUTTON 

KEYBD I/P R5/ 

KEYBD I/P R6/TIMER B: TOGGLE /PULSE OUTPUT 

KEYBD I/P R7/TIMER A: TOGGLE /PULSE OUTPUT 

DC02 56322 DATA DIRECTION PORT A 

DC03 56323 DATA DIRECTION PORT B 

DC04 56324 TA LO 



U 



1 ) 
U 



u 



u 
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MEMORY 
ADDRESS 
LABEL 



HEXADECIMAL DECIMAL 
ADDRESS ADDRESS 



DESCRIPTION 



6526 CIA#1, COMPLEX INTERFACE ADAPTER #1 
KEYBOARD, JOYSTICK, PADDLES, LIGHTPEN, FAST DISK 

TA HI (TIMER A) 

TBLO 

TB HI (TIMER B) 

TOD (TENTHS) 

TOD (SECONDS) 

TOD (MINUTES) 

TOD (HOURS) 

SERIAL DATA REGISTER 

INTERRUPT CONTROL REGISTER 

CONTROL REGISTER A 

CONTROL REGISTER B 

6526 CIA#2 COMPLEX INTERFACE ADAPTER #2 
USER PORT,RS-232,SERIAL BUS,VIC MEMORY,NMI 



DITIH 


DC05 


56325 


D1T2L 


DCCW 


56326 


D1T2H 


DC07 


56327 


DlTODl 


DC08 


56328 


DITODS 


DC09 


56329 


DITODM 


DCOA 


56330 


DITODH 


DCOB 


56331 


DISDR 


DCOC 


56332 


DIICR 


DCOD 


56333 


DICRA 


DCOE 


56334 


DICRB 


DCOF 


56335 



D2PRA 



DDOO 



56576 



PORT A, SERIAL BUS, RS-232, VA14 


& VA15 


BITS 







PRAO : VA14 


1 


PRAl : VA15 


2 


PRA2 : RS232 DATA 




OUTPUT 


3 


PRA3 : SERIAL ATN 




OUTPUT 


4 


PRA4 : SERIAL CLK 




OUTPUT 


5 


PRA5 : SERIAL DATA 




OUTPUT 


6 


PRA6 : SERUL CLK INPUT 


7 


PRA7 : SERIAL DATA INPUT 



! I 



I I 



n 
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C128 Memory Map (continued) 



MEMORY 
ADDRESS 
LABEL 



D2PRfi 



DMA ST 



HEXADECIMAL DECIMAL 
ADDRESS ADDRESS 



DESCRIPTION 



DDOl 



DFOO 



56577 



D2DDRA 


DD02 


56578 


D2DDRB 


DD03 


56579 


D2T1L 


DD04 


56580 


D2T1H 


DD05 


56581 


D2T2L 


OD06 


56582 


D2T2H 


DD07 


56583 


D2T0D1 


DD08 


56584 


D2TODS 


DD09 


56585 


D2TODM 


DDOA 


56586 


D2TODH 


DDOB 


56587 


D2SDR 


DDOC 


56588 


D2ICR 


DDOD 


56589 


D2CRA 


DDOE 


56590 


D2CRB 


DDOF 


56591 


lOl 


DEOO 


56832 


I02 


DFOO 


57088 



57088 



PORT B, USER PORT, RS-232 
BITS 




1 

2 

3 

4 

5 
6 



PRBO : USER PORT / RS-232 

RECEIVED DATA 

PRBl : USER PORT / RS-232 

REQUEST TO SEND 

PRB2 : USER PORT / RS-232 

DATA TERMINAL READY 

PRB3 : USER PORT / RS-232 

RING INDICATOR 

PRB4 : USER PORT / RS-232 

CARRIER DETECT 

PRB5 : USER PORT 

PRB6 : USER PORT / RS-232 

CLEAR TO SEND 

PRB7 : USER PORT / RS-232 

DATA SET READY 



DATA DIRECTION PORT A 

DATA DIRECTION PORT B 

TALO 

TA HI (TIMER A) 

TBLO 

TB HI (Tn^R B) 

TOD (TENTHS) 

TOD (SECONDS) 

TOD (MINUTES) 

TOD (HOURS) 

SERIAL DATA REGISTER 

INTERRUPT CONTROL REGISTERS 

(NMPS) 

CONTROL REGISTER A 

CONTROL REGISTER B 

EXPANSION I/O SLOT (RESERVED) 

EXPANSION I/O SLOT (RESERVED) 

C128 DMA CONTROLLER FOR 
EXPANSION RAM ACCESS 
OPTIONAL DEVICE MAPPED INTO 
I02 BLOCK VU SYSTEM 
EXPANSION PORT (PRELIMINARY) 
DMA CONTROLLER STATUS 
REGISTER (READ ONLY) 



u 



u 






u 



UJ 



u 



u 



u 
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MEMORY 
ADDRESS 
LABEL 



HEXADECIMAL DECIMAL 
ADDRESS ADDRESS 



DESCRIPTION 



I ; 



n 



n 



DMACMD 



DFOl 



57089 



DMA ADL 


DF02 


57090 


DMA ADH 


DF03 


57091 


DMALO 


Dr04 


57092 


DMA HI 


DF05 


57093 


DMA BNK 


DF06 


57094 




INTERRUPT 

PENDING (1 = DVT. 

WAITING TO BE 

SERVICED) 

END OF BLOCK 

(1= TRANSFER 

COMPLETE) 

FAULT (1= BLOCK 

VERIFY ERROR) 

SIZE (0 = EXP. 
MEMORY = 
128K) 
(1 = EXP. 
MEMORY = 
512K) 
VERSION 



DMA CONTROLLER COMMAND 
REGISTER 



7 


EXECUTE 


6 


RESERVED 


5 


LOAD (1 = ENABLE 




AUTO = LOAD) 


4 


$FF00 (1 = DISABLE $FF00 




DECADES) 


3 


RESERVED 


2 


RESERVED 


1-0 


MODE (00= TRANSFER 




FROM INTERNAL TO 




EXTERNAL, 




01 = FROM EXT TO INT, 




10 = SWAP, 11 = VERIFY) 



LSB OF INTERNAL (C128) ADDRESS 

TO ACCESS 

MSB OF INTERNAL (C128) ADDRESS 

TO ACCESS 

LSB OF EXTERNAL EXPANSION 

RAM TO ACCESS 

MSB OF EXTERNAL EXPANSION 

RAM TO ACCESS 

64K EXTERNAL RAM BANK 

BITS ($DF06) 



536 COMMODORE 128 



C128 Memory Map (continued) 



MEMORY 
ADDRESS 
LABEL 



HEXADECIMAL 
ADDRESS 



DECIMAL 
ADDRESS 



DESCRIPTION 



7-3 
2-0 



NOT USED 

EXPANSION BANK NUMBER 



DMA DAL 


DF07 


57095 


DMADAH 


DF08 


57096 


DMA SUM 


DF09 


57097 



LSB OF BYTE COUNT 

MSB OF BYTE COUNT (BLOCK 

COUNT) 

INTERRUPT MASK REGISTER 



DMA VER 



DFOA 



57098 



EOOO 



57344 



INTERRUPT ENABLE 

(1= INTERRUPTS ENABLED) 

END OF BLOCK MASK 

(1 = INTERRUPT ON END 

OF BLOCK) 

VERIFY ERROR 

(1 = INTERRUPT ON VERIFY 

ERROR) 

ADDRESS CONTROL REGISTER 

BITS 7 AND 6 

0,0 = INCREMENT BOTH ADDRESS 
(DEFAULT) 

0,1 = FIX EXPANSION ADDRESS. 

1.0 = FIX C128 ADDRESS. 

1.1 = FIX BOTH ADDRESSES. 
KERNAL ROM (8K OPERATING 
SYSTEM, $E000-$FFFF) 



MMU SECONDARY REGISTERS 



MMUCR 


FFOO 


65280 


CONFIGURATION REGISTER 
(SECONDARY) 


LCRA 


FFOl 


65281 


LOAD CONFIGURATION 
REGISIER A 


LCRB 


FF02 


65282 


LOAD CONFIGURATION 
REGISTER B 


LCRC 


FF03 


65283 


LOAD CONFIGURATION 
REGISTER C 


LCRD 


FF04 


65284 


LOAD CONFIGURATION 
REGISTER D 








BITS 


($FF00-$FF04) 




7-6 


RAM BANK (0-3) 








5-4 


ROM HI (SYSTEM, INT, 
EXT, RAM) 








3-2 


ROM MID (SYSTEM, INT, 
EXT, RAM) 








1 


ROM LO (SYSTEM, RAM) 











I/O (I/O ELSE ROM- 










HI) 
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KERNAL JUMP TABLE 
NEW ENTRIES FOR CI 28 

JMP SPIN SPOUT FF47 

JMP CLOSE ALL FF4A 

JMP C64MODE FF4D 

JMP DMA CALL FF50 



JMP BOOT CALL FF53 
JMP PHOEraX FF56 



JMP LKUPLA 


FF59 


JMP LKUPSA 


FF5C 


JMP SWAPPER 


FF5F 


JMP DLCHR 


FF62 


JMP PFKEY 


FF65 


JMP SETBNK 


FF68 


JMP GETCFG 


FF6B 


JMP JSRFAR 


FF6E 


JMP JMPFAR 
JMP INDFET 


FF71 
FF74 


JMPINDSTA 


FF77 


JMP INDCMP 


FF7A 


JMPPRIMM 


F1<7D 



65351 


SET UP FAST SERIAL PORT 




FOR I/O 


65354 


CLOSE ALL LOGICAL 




FILES FOR A DEVICE 


65357 


RECONFIGURE SYSTEM 




AS A C64 (NO RETURN) 


65360 


INirUTE DMA REQUEST 




TO EXTERNAL RAM 




EXPANSION, SEND 




COMMAND TO DMA 




DEVICE 


65363 


BOOT LOAD PROGRAM 




FROM DISK 


65366 


CALL ALL FUNCTION 




CARDS' COLD START 




ROUTINES, INITLU.IZE 


65369 


SEARCH TABLES FOR 




GIVEN LA 


65372 


SEARCH TABLES FOR 




GIVEN SA 


65375 


SWITCH BETWEEN 40 AND 




80 COLUMNS (EDITOR) 


65378 


INIT 80-COL CHARACTER 




RAM (EDITOR) 


65381 


PROGRAM FUNCTION KEY 




(EDITOR) 


65384 


SET BANK FOR I/O 




OPERATIONS 


65387 


LOOKUP MMU DATA FOR 




GIVEN BANK 


65390 


JSR TO ANY BANK, RTS 




TO CALLING BANK 


65393 


JMP TO ANY BANK 


65396 


LDA (FETVEC), Y FROM 




ANY BANK 


65499 


STA (STAVEC), Y TO ANY 




BANK 


65402 


CMP (CMPVEC),Y TO ANY 




BANK 


65405 


PRINT IMMFDIATE UTILITY 




(ALWAYS JSR TO THIS 




ROUTINE) 



JMPCINT 



STANDARD KERNAL JUMP TABLE 

FF80 65408 RELEASE NUMBER OF 

KERNAL 
FF81 65409 INIT EDITOR & DISPLAY 

CHIPS (EDITOR) 
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C128 Memory Map (continued) 

STANDARD KERNAL JUMP TABLE 



JMPIOINIT 


FF84 




65412 


JMP RAMTAS 


FF87 




65415 


JMP RESTOR 


FliKA 




65418 


JMP VECTOR 


FF8D 




65421 


JMP SETMSG 


FF90 




65424 


JMP SECND 


FF93 




65427 


JMPTKSA 


FF96 




65430 


JMP MEMTOP 


FF99 




65433 


JMPMEMBOT 


FF9C 




65436 


JMP KEY 


FF9F 




65439 


JMP SETTMO 


FFA2 




65442 


JMPACPTR 


FFA5 




65445 


JMP CIOUT 


FFA8 




65448 


JMP UNTLK 


FFAB 




65451 


JMPUNLSN 


FFAE 




65454 


JMP LISTN 


FFBl 




65457 


JMP TALK 


FFB4 




65460 


JMPREADSS 


FFB7 




65463 


JMP SETLFS 


FFBA 




65460 


JMP SETNAM 


FFBD 




65469 


JMP aOPEN) 


FFCO 


OPEN 


65472 


JMP aCLOSE) 


FFC3 


CLOSE 


65475 


JMP (ICHKIN) 


FFC6 


CHKIN 


65478 


JMP aCKOUT) 


FFC9 


CKOUT 


65481 


JMP aCLRCH) 


FFCC 


CLRCH 


65484 


JMP (IBASIN) 


FFCF 


BASIN 


65487 


JMP (IBSOUT) 


FFD2 


BSOUT 


65490 


JMP LOADSP 


FFD5 




65493 


JMP SAVESP 


FFD8 




65496 


JMP SE ITIM 


FFDB 




65599 


JMP RDl IM 


FFDE 




65502 


JMP (ISTOP) 


FFEl 


STOP 


65505 


JMP (IGETIN) 


FFE4 


GETIN 


65508 


JMP (ICLALL) 


FFE7 


CLALL 


65511 



INIT I/O DEVICES (PORTS, 

TIMERS, ETC.) 

INITIALIZE RAM AND 

BUFFERS FOR SYSTEM 

RESTORE VECTORS TO 

INITIAL SYSTEM 

CHANGE VECTORS FOR 

USER 

CONTROL O.S. MESSAGE 

SEND SA AFTER LISTEN 

SEND SA AFTER TALK 

SET/READ TOP OF SYSTEM 

RAM 

SET/READ BOTTOM OF 

SYSTEM RAM 

SCAN KEYBOARD 

(EDITOR) 

SET TIMEOUT IN IEEE 

(RESERVED) 

HANDSHAKE SERLVL BYTE 

IN 

HANDSHAKE SEIUAL BYTE 

OUT 

SEND UNTALK OUT SEIUAL 

SEND UNLISTEN OUT 

SERIAL 

SEND LISTEN OUT SERIAL 

SEND TALK OUT SERIAL 

RETURN I/O STATUS BYTE 

SET LA, FA, SA 

SET LENGTH AND FILE 

NAME ADDRESS 

OPEN LOGICAL FILE 

CLOSE LOGICAL FILE 

SET CHANNEL IN 

SET CHANNEL OUT 

RESTORE DEFAULT I/O 

CHANNEL 

INPUT FROM CHANNEL 

OUTPUT TO CHANNEL 

LOAD FROM FILE 

SAVE TO FILE 

SET INTERNAL CLOCK 

READ INTERNAL CLOCK 

SCAN STOP KEY 

READ BUFFERED DATA 

CLOSE ALL FILES AND 

CHANNELS 



u 
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STA^fDARD KERNAL JUMP TABLE 


JMPUDTIM 


FFEA 


CLOCK 


65514 


INCREMENT INTERNAL 
CLOCK 


JMP SCRORG 


FEED 




65517 


RETURN SCREEN WINDOW 
SIZE (EDITOR) 


JMPPLOT 


FFFO 




65520 


READ/SET X,Y CURSOR 
COORD (EDITOR) 


JMP lOBASE 


FFF3 




65523 


RETURN I/O BASE 


SYSTEM 


FFF8 




65528 


OPERATING SYSTEM 
VECTOR (RAMI) 


NMI 


FFFA 




65530 


PROCESSOR NMI VECTOR 


RESET 


FFFC 




65532 


PROCESSOR RESET 
VECTOR 


IRQ 


FFFE 




65534 


PROCESSOR IRQ/BRK 
VECTOR 



n 

I ! 

n 
n 

n 



KERNAL/EDITOR FLAGS AND 
SHADOW REGISTERS 



The following symbols are used by the CI 28 Editor. Note that the Editor IRQ VIC 
screen handler depends upon them. In most cases the contents of these locations will be 
placed directly into the appropriate register and should be used instead of the actual 
register. For example, to change the location of the character set used by VIC, use VMl 
($0A2C) instead of VIC register 24 ($D018). VMl will be used by the editor to update 
VIC register 24. 



n 



ADDRESS/NAME 

$00D8/GRAPHM 
$00D9/CHAREN 
$0A2CA^M1 

$0A2DA'M2 

$0A2EATVI3 
$0A2FAnV14 
$0A34/SPLIT 

$0A2B/CURMOD 
$0A21/PAUSE 



EXPLANATION 

SEE BELOW. IF = $FF THEN EDITOR LEAVES VIC ALONE. 

MASK FOR 8502 /CHAREN BIT. 

VIC TEXT MODE VIDEO MATRIX & CHARACTER BASE 

POINTER. 

VIC GRAPHIC MODE VIDEO MATRIX & BIT MAP 

POINTER. 

8563 TEXT DISPLAY BASE ADDRESS. 

8563 ATTRIBUTE BASE ADDRESS. 

IN SPLIT SCREEN MODE, CONTAINS VALUE FOR 

MIDDLE RASTER IRQ. 

8563 CURSOR MODE. 

CONTROL S FLAG (JN EFFECT = $13) 
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EXPLANATION OF VARIOUS KERNAL/EDITOR FLAG BYTES, ETC. 



ADDRESS SYMBOL 



DESCRIPnON 



0000 

0001 
00F7 
OOFS 
00D3 
0A22 
0A26 
00F9 
00O8 
00D7 
0A04 



D6510 

R6510 

LOCKS 

SCROLL 

SHFLAG 

RPTFLG 

BLNON 

BEEPER 

GRAPHM 

MODE 



CASE 
OFF 



(IN) (OUT) (IN) (OUT) (OUT) (OUT) (OUT) 
CAPKEY CASMTR CASSEN CASWRT CHAREN HIRAM LORAM 
CTLS ______ 

LINKER 



ALT ALPHA CTRL 



SHIFT 



ALL NONE 

ON BLNK 

ON — 

MCM SPLIT 

40/80 — 

INIT_ CHRSET CINT 
STATUS 



BMM — 



BASIC 



u 

J 
f 

U 

u 
u 

J 



Notes on Kernal Symbols: 

init-Status. See also above. Lets system know what has been initialized and what 

hasn't. Set to $00 by a reset but untouched by NMI. 
System-Vector. Where the Kernal goes when it has to go somewhere. It's set to 

BASIC cold at reset. BASIC itself sets it to BASIC warm after it has initialized. 

The monitor respects it too. 
System. Vector in RAMI at $FFF8. Set at power-up to C128MODE, user may redirect 

it to his code. Taken at reset always providing user with control (protection) from 

reset. 
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HEX 


DECIMAL 




LABEL 


ADDRESS 


LOCATION 


DESCRIPTION 


D6510 


0000 





6510 On-Chip Data-Direction Register 


R6510 


0001 


1 


6510 On-Chip 8-Bit Input/Output 
Register 




0002 


2 


Unused 


ADRAYl 


0003-0004 


3^ 


Jump Vector: Convert Floating- 
Integer 


ADRAY2 


0005-0006 


5-6 


Jump Vector: Convert Integer — 
Floating 


CHARAC 


0007 


7 


Search Character 


EIVDCHR 


0008 


8 


Flag: Scan for Quote at End of String 



u 



U 
U 



- 












n 
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1 

1 




HEX 


DECIMAL 






r> 


LABEL 


ADDRESS 


LOCATION 


DESCRIKI'ION 






TRMPOS 


0009 


9 


Screen Column From Last TAB 






VERCK 


OOOA 


10 


Flag: = Load, 1 = Verify 




r 


COUNT 


OOOB 


11 


Input Buffer Pointer/No. of Subscripts 




DIMFLG 


OOOC 


12 


Flag: Default Array DIMension 




1 


VALTYP 


GOOD 


13 


Data Type: $FF = String, $00 = 
Numeric 




-I 


INTFLG 


OOOE 


14 


Data Type: $80 = Integer, $00 = 
Floating 






GARBFL 


OOOF 


15 


Flag: DATA scan/LIST quote/ 
Garbage Coll 




n 
1 


SUBFLG 


0010 


16 


Flag: Subscript Ref / User Function 
Call 






INPFLG 


0011 


17 


Flag: $00 = INPUT, $40 = GET, 












$98 = READ 








TANSGN 


0012 
0013 


18 
19 


Flag: TAN sign / Comparison Result 
Flag: INPUT Prompt 






LINNUM 


0014-0015 


20-21 


Temp: Integer Value 




n 


TEMPPT 


0016 


22 


Pointer: Temporary String Stack 




LASTPT 


0017-0018 


23-24 


Last Temp String Address 




TEMPST 


0019-0021 


25-33 


Stack for Temporary Strings 






INDEX 


0022-0025 


34-37 


Utility Pointer Area 




■n 


RFSHO 


0026-002A 


38-42 , 


Floating-Point Product of Multiply 






IXIIAB 


002B-002C 


43-44 


Pointer: Start of BASIC Text 






VARTAB 


002D-002E 


45-46 


Pointer: Start of BASIC Variables 






ARYTAB 


002F-0030 


47-48 


Pointer: Start of BASIC Arrays 




H 


STREND 


0031-0032 


49^50 


Pointer: End of BASIC Arrays ( + 1) 




! 


FRETOP 


0033-0034 


51-52 


Pointer: Bottom of String Storage 






FRESPC 


0035-0036 


53-54 


Utility String Pointer 






MEMSIZ 


0037-0038 


55-56 


Pointer: Highest Address Used by 










BASIC 




CURLIN 


0039-003A 


57-58 


Current BASIC Line Number 






OLDLIN 


003B-003C 


59-60 


Previous BASIC Line Number 




^ 


OLDTXT 


003D-003E 


61-62 


Pointer: BASIC Statement for CONT 






DATLIN 


003F-0040 


63-64 


Current DATA Line Number 






DATPTR 


0041-0042 


65-66 


Pointer: Current DATA Item Address 




-| 


INPPTR 


0043-0044 


67-68 


Vector: INPUT Routine 




VARNAM 


0045-0046 


69-70 


Current BASIC Variable Name 






VARPNT 


0047-0048 


71-72 


Pointer: Current BASIC Variable 
Data 




■] 


FORPNT 


0049-004A 


73-74 


Pointer: Index Variable for FOR/NEXT 






004B-0060 


75-96 


Temp Pointer / Data Area 






FACEXP 


0061 


97 


Floating-Point Accumulator #1: 




^ 








Exponent 




FACHO 


0062-0065 


98-101 


Floating Accum. #1: Mantissa 




1 




FACSGN 


0066 


102 


Floating Accum. #1: Sign 
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Commodore 6^ 


\ Memory Map (continued) 






HEX 


DECIMAL 




LABEL 


ADDRESS 


LOCATION 


DESCRIPTION 


SGNFLG 


0067 


103 


Pointer: Series Evaluation Constant 


BITS 


0068 


104 


Floating Accum. #1: Overflow Digit 


ARGEXP 


0069 


105 


Floating-Point Accumulator #2: 
Exponent 


ARGHO 


006A-006D 


106-109 


Floating Accum. #2: Mantissa 


ARGSGN 


006E 


110 


Floating Accum. #2: Sign 


ARISGN 


006F 


111 


Sign Comparison Result: Accum. #1 

vs#2 


FACOV 


0070 


112 


Floating Accum. #1. Low-Order 
(Rounding) 


FBUFPT 


0071-0072 


113-114 


Pointer: Cassette Buffer 


CHRGET 


0073-008A 


115-138 


Subroutine: Get Next Byte of BASIC 
Text 


CHRGOT 


0079 


121 


Entry to Get Same Byte of Text 
Again 


TXTPTR 


007A-007B 


122-123 


Pointer: Current Byte of BASIC Text 


RNDX 


008B-008F 


139-143 


Floating RND Function Seed Value 


STATUS 


0090 


144 


Kernal I/O Status Word: ST 


STKEY 


0091 


145 


Flag: STOP key / RVS key 


SVXT 


0092 


146 


Timing Constant for Tape 


VERCK 


0093 


147 


Flag: = Load, 1 = Verify 


C3P0 


0094 


148 


Flag: Serial Bus— Output Char. 
Buffered 


BSOUR 


0095 


149 


Buffered Character for Serial Bus 


SYNO 


0096 


150 


Cassette Sync No. 




0097 


151 


Temp Data Area 


LDTND 


0098 


152 


No. of Open Files / Index to File 
Table 


DFLTN 


0099 


153 


Default Input Device (0) 


DFLTO 


009A 


154 


Default Output ^CMD) Device (3) 


PRTY 


009B 


155 


Tape Character Parity 


DPSW 


009C 


156 


Flag: Tape Byte-Received 


MSGFLG 


009D 


157 


Flag: $80 = Direct Mode, $00 = 
Program 


PTRl 


009E 


158 


Tape Pass 1 Error Log 


PTR2 


009F 


159 


Tape Pass 2 Error Log 


TIME 


00AO-O0A2 


160-162 


Real-Time Jiffy Clock (approx) 1/60 

Sec 
Temp Data Area 




OOA3-O0A4 


163-164 


CNTDN 


00A5 


165 


Cassette Sync Countdown 


BUFPNT 


00A6 


166 


Pointer: Tape I/O Buff^er 


INBIT 


00A7 


167 


RS-232 Input Bits / Cassette Temp 


BITCI 


00A8 


168 


RS-232 Input Bit Count / Cassette 

Temp 
RS-232 Flag: Check for Start Bit 


RINONE 


00A9 


169 



u 

I 

u 
U 
U 



u 
u 



u 



u 



u 



u 



n 
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HEX 


DECIMAL 




LABEL 


ADDRESS 


LOCATION 


DESCRirnON 


RIDATA 


OOAA 


170 


RS-232 Input Byte BulTer/Cassette 
Temp 


RIPRTY 


OOAB 


171 


RS-232 Input Parity / Cassette Short 
Cnt 


SAL 


OOAC-OOAD 


172-173 


Pointer: Tape Buffer/Screen ScroUing 


EAL 


OOAE-OOAF 


174-175 


Tape End Addresses / End of Program 


CMPO 


OOBO-OOBl 


176-177 


Tape Timing Constants 


TAPEl 


00B2-00B3 


178-179 


Pointer: Start of Tape Buffer 


BITTS 


00B4 


180 


RS-232 Out Bit Count / Cassette 
Temp 


NXTBIT 


00B5 


181 


RS-232 Next Bit to Send / Tape EOT 
Flag 


RODATA 


00B6 


182 


RS-232 Out Byte Buffer 


FNLEN 


00B7 


183 


Lengtii of Current File Name 


LA 


00B8 


184 


Current Logical File Number 


SA 


00B9 


185 


Current Secondary Address 


FA 


OOBA 


186 


Current Device Number 


FNADR 


OOBB-OOBC 


187-188 


Pointer: Current File Name 


ROPRTY 


OOBD 


189 


RS-232 Out Parity / Cassette Temp 


FSBLK 


OOBE 


190 


Cassette ReadAVrite Block Count 


MYCH 


OOBF 


191 


Serial Word Buffer 


CASl 


OOCO 


192 


Tape Motor Interlock 


STAL 


00C1-00C2 


193-194 


I/O Start Address 


MEMUSS 


00C3-00C4 


195-196 


Tape Load Temps 


LSTX 


00C5 


197 


Current Key Pressed: CHR$(n) = 
No Key 


NDX 


00C6 


198 


No. of Chars, in Keyboard Buffer 
(Queue) 


RVS 


00C7 


199 


Flag: Print Reverse Chars.— 1 = 
Yes, = Not Used 


INDX 


00C8 


200 


Pointer: End of Logical Line for 
INPUT 


LXSP 


00C9-00CA 


201-202 


Cursor X-Y Pos. at Start of INPUT 


SFDX 


OOCB 


203 


Flag: Print Shifted Chars. 


BLNSW 


OOCC 


204 


Cursor Blink enable: = Flash 
Cursor 


BLNCT 


OOCD 


205 


Tuner: Countdown to Toggle Cursor 


GDBLN 


OOCE 


206 


Character Under Cursor 


BLNON 


OOCF 


207 


Flag: Last Cursor Blink On/Off 


CRSW 


OODO 


208 


Flag: INPUT or GET from Keyboard 


PNT 


00D1-00D2 


209-210 


Pointer: Current Screen Line Address 


PNTR 


00D3 


211 


Cursor Column on Current Line 


QTSW 


00D4 


212 


Flag: Editor in Quote Mode, $00 = 

NO 
Physical Screen Luie Length 


LNMX 


00D5 


213 
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Commodore 64 Memory Map (continued) 






HEX 


DECIMAL 




LABEL 


ADDRESS 


LOCATION 


DESCRIPTION 


TBLX 


00D6 


214 


Current Cursor Physical Line 
Number 




00D7 


215 


Temp Data Area 


INSRT 


00D8 


216 


Flag: Insert Mode, >0 = # INSTs 


LDTBl 


00D9-00F2 


217-242 


Screen Line Linl( Table / Editor 
Temps 


USER 


00F3-O0F4 


243-244 


Pointer: Current Screen Color RAM 

loc. 
Vector: Keyboard Decode Table 


KEYTAB 


00F5-OOF6 


245-246 


RIBUF 


00F7-O0F8 


247-248 


RS-232 Input Buffer Pointer 


ROBUF 


00F9-fl0FA 


249-250 


RS-232 Output Buffer Pointer 


FREKZP 


OOFB-OOFE 


251-254 


Free 0-Page Space for User Programs 


BASZPT 


OOFF 


255 


BASIC Temp Data Area 




0100-OlFF 


256-511 


Micro-Processor System Stack Area 




0100-OlOA 


256-266 


Floating to String Work Area 


BAD 


010(M)13E 


256-318 


Tape Input Error Log 


BUF 


020(M)2S8 


512-600 


System INPUT Buffer 


LAT 


0259-0262 


601-610 


KERNAL Table: Active Logical FUe 

No's. 
KERNAL Table: Device No. for Each 

File 
KERNAL Table: Second Address 


FAT 


0263-O26C 


611-620 


SAT 


026D-0276 


621-630 








Each File 


KEYD 


0277-0280 


631-640 


Keyboard Buffer Queue (FIFO) 


MEMSTR 


0281-0282 


641-642 


Pointer: Bottom of Memory for O.S. 


MEMSIZ 


0283-0284 


643-644 


Pointer: Top of Memory for O.S. 


riMOUT 


0285 


645 


Flag: Kemal Variable for IEEE 
Timeout 


COLOR 


0286 


646 


Current Character Color Code 


GDCOL 


0287 


647 


Background Color Under Cursor 


HIBASE 


0288 


648 


Top of Screen Memory (Page) 


XMAX 


0289 


649 


Size of Keyboard Buffer 


RFIFLG 


028A 


650 


Flag: REPEAT Key Used, $80 = 
Repeat 


KOUNT 


028B 


651 


Repeat Speed Counter 


DELAY 


028C 


652 


Repeat Delay Counter 


SHFLAG 


028D 


653 


Flag: Keyb'rd SHIFT Key / CTRL 
Key / Key 


LSTSHF 


028E 


654 


Last Keyboard Shift Pattern 


KEYLOG 


028F-0290 


655-656 


Vector: Keyboard Table Setup 


MODE 


0291 


657 


Flag: $00 = Disable SHIFT Keys, 
$80 = Enable SHIFT Keys 


AUTODN 


0292 


658 


Flag: Auto Scroll Down, = ON 


M51CTR 


0293 


659 


RS-232: 6551 Control Register Image 


M51CDR 


0294 


660 


RS-232: 6551 Command Register 
Image 



u 

LI 



U 
U 



u 






n 
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LABEL 



M51AJB 

RSSTAT 

BITNUM 

BAUDOF 

RIDBE 

RIDBS 

RODBS 

RODBE 

ffiQTMP 
ENABL 



lERROR 

IMAIN 

ICRNCH 

IQPLOP 

IGONE 

lEVAL 

SAREG 

SXREG 

SYREG 

SPREG 

USRPOK 

USRADD 

CINV 

CBINV 

NMINV 

lOPEN 

ICLOSE 

ICHKIN 

ICKOUT 

ICLRCH 

IBASIN 

IBSOUT 

ISTOP 

IGETIN 

ICLALL 

USRCMD 



HEX 
ADDRESS 



0295-0296 

0297 

0298 

0299-029A 

029B 

029C 

029D 

029E 

029F-02A0 

02A1 

02A2 

02A3 

02A4 

02A5 
02A6 

02A7-02FF 

0300-O301 

0302-0303 

0304-0305 

0306-0307 

0308-0309 

030A-030B 

030C 

030D 

030E 

030F 

0310 

0311-0312 

0313 

0314-0315 

0316-0317 

0318-0319 

031A-031B 

031C-031D 

031E-031F 

0320-0321 

0322-0323 

0324-0325 

0326-0327 

0328-0329 

032A-032B 

032C-032D 

032E-032F 



DECIMAL 
LOCATION 



661-662 

663 

664 

665-666 

667 

668 

669 

670 

671-672 

673 

674 

675 

676 

677 
678 

697-767 

768-769 

770-771 

772-773 

774-775 

776-777 

778-779 

780 

781 

782 

783 

784 

785-786 

787 

788-789 

790-791 

792-793 

794-795 

796-797 

798-799 

800-801 

802-803 

804-805 

806-807 

808-809 

810-811 

812-813 

814-815 



DESCRIPTION 



RS-232 Non-Standard BPS 

(Tiine/2-100) USA 
RS-232: 6551 Status Register Image 
RS-232 Number of Bits Left to Send 
RS-232 Baud Rate: FuU Bit Time (m^) 
RS-232 Index to End of Input Buffer 
RS-232 Start of Input Buffer (Page) 
RS-232 Start of Output Buffer (Page) 
RS-232 Index to End of Output 

Buffer 
Holds IRQ Vector During Tape I/O 
RS-232 Enables 

TOD Sense During Cassette I/O 
Temp Storage For Cassette Read 
Temp DIIRQ Indicator For Cassette 

Read 
Temp for Line Index 
PAL/NTSC Flag, = NTSC, 1 = 

PAL 
Unused 

Vector: Print BASIC Error Message 
Vector: BASIC Warm Start 
Vector: Tolcenize BASIC Text 
Vector: BASIC Text LIST 
Vector: BASIC Char. Dispatch 
Vector: BASIC Token Evaluation 
Storage for 6502 .A Register 
Storage for 6502 .X Register 
Storage for 6502 .Y Register 
Storage for 6502 .SP Register 
USR Function Jump Instr (4C) 
USR Address Low Byte / High Byte 
Unused 

Vector: Hardware IRQ Interrupt 
Vector: BRK Instr, Interrupt 
Vector: Non-Maskable Interrupt 
KERNAL OPEN Routine Vector 
KERNAL CLOSE Routine Vector 
KERNAL CHKIN Routine Vector 
KERNAL CHKOUT Routine Vector 
KERNAL CLRCHN Routine Vector 
KERNAL CHRIN Routine Vector 
KERNAL CHROUT Routine Vector 
KERNAL STOP Routine Vector 
KERNAL GETIN Routine Vector 
KERNAL CLALL Routine Vector 
User-Defined Vector 
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Commodore 64 Memory Map (continued) 





HEX 


DECIMAL 




LABEL 


ADDRESS 


LOCATION 


DESCRIPTION 


ILOAD 


0330-0331 


816-817 


KERNAL LOAD Routine Vector 


ISAVE 


0332-0333 


818-«19 


KERNAL SAVE Routine Vector 




0334-033B 


820-827 


Unused 


TBUFFR 


033C-03FB 


828-1019 


Tape I/O Buffer 




03FC-03FF 


1020-1023 


Unused 


VICSCN 


0400-07FF 


1024-2047 


1024 Byte Screen Memory Area 




0400-07E7 


1024-2023 


Video Matrix: 25 Lines x 40 
Columns 




07F8-07FF 


2040-2047 


Sprite Data Pointers 




0800-9FFF 


2048-40959 


Normal BASIC Program Space 




8000-9FFF 


32768-40959 


VSP Cartridge ROM— 8192 Bytes 




AOOO-BFFF 


40960-49151 


BASIC ROM— 8192 Bytes (or 8K 
RAM) 




COOO-CFFF 


49152-53247 


RAM-4096 Bytes 




DOOO-DFFF 


53248-57343 


Input/Output Devices and Color 

RAM 
or Cliaracter Generator ROM 
or RAM— 4096 Bytes 




EOOO-FFFF 


57344-65535 


KERNAL ROM— 8192 Bytes (or 8K 
RAM) 





u 
u 





u 



COMMODORE 64 INPUT/OUTPUT ASSIGNMENTS 



HEX 


DECIMAL 


BITS 


DESCRIPTION 


0000 





7-0 


MOS 6510 Data Direction Register 
(xxlOllll) 

Bit=l: Output, Bit = 0: 
Input, x = Either 


0001 


1 




MOS 6510 Micro-Processor On-Cliip 
I/O Port 









/LORAM Signal (0=Switcli BASIC 
ROM Out) 






1 


/HIRAM Signal (0 = Switch Kernal 
ROM Out) 






2 


/CHAREN Signal (0 = Switch Char. 
ROM In) 






3 


Cassette Data Output Line 






4 


Cassette Switch Sense 
1 = Switch Closed 






5 


Cassette Motor Control 
= ON, 1 = OFF 






6-7 


Undefined 



u 
u 
u 
u 

1 
L 

u 
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HEX 



ri 



n 



n 



D00O-D02E 

DOOO 
DOOl 
D002 
D003 
D004 
D005 
D006 
D007 
D008 
D009 
DOOA 
DOOB 
DOOC 
DOOD 
DOOE 
DOOF 
DOlO 
DOll 



DECIMAL 



R 



n 



D012 

D013 
D014 
D015 
D016 



D017 
D018 



53248-54271 

53248 
53249 
53250 
53251 
53252 
53253 
53254 
53255 
53256 
53257 
53258 
53259 
53260 
53261 
53262 
53263 
53264 
53265 



53266 

53267 
53268 
53269 
53270 



53271 
53272 



BITS 



7 

6 

5 

4 

3 
2-0 



7-6 

5 

4 

3 

2-0 

7-4 



DESCRIPTION 



MOS 6566 VIDEO INTERFACE 

CONTROLLER (VIC) 
Sprite X Pos 
Sprite Y Pos 
Sprite 1 X Pos 
Sprite 1 Y Pos 
Sprite 2 X Pos 
Sprite 2 Y Pos 
Sprite 3 X Pos 
Sprite 3 Y Pos 
Sprite 4 X Pos 
Sprite 4 Y Pos 
Sprite 5 X Pos 
Sprite 5 Y Pos 
Sprite 6 X Pos 
Sprite 6 Y Pos 
Sprite 7 X Pos 
Sprite 7 Y Pos 

Sprites 0-7 X Pos (msb of X coord.) 
VIC Control Register 
Raster Compare: (Bit 8) See 53266 
Extended Color Text Mode: 1 = 

Enable 
Bit-Map Mode: 1 = Enable 
Blank Screen to Border Color: = 

Blank 
Select 24/25 Row Text Display: 1 = 

25 Rows 
Smooth Scroll to Y Dot-Position (0-7) 
Read Raster / Write Raster Value for 

Compare IRQ 
Light-Pen Latch X Pos 
Light-Pen Latch Y Pos 
Sprite Display Enable: 1 = Enable 
VIC Control Register 
Unused 

ALWAYS SET THIS BIT TO 
Multi-Color Mode: 1 = Enable (Text 

or Bit-Map) 
Select 38/40 Column Text Display: 1 

= 40 Cols 
Smooth Scroll to X Pos 
Sprites 0-7 Expand 2 x Vertical (Y) 
VIC Memory Control Register 
Video Matrix Base Address (inside 

VIC) 
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Commodore 64 


f Input/Output Assignments (continued) 


HEX 


DECIMAL 


BITS 


DESCRIPTION 






3-1 


Character Dot-Data Base Address 
(inside VIC) 


D019 


53273 




VIC Interrupt Flag Register (Bit = 
1: IRQ Occurred) 






7 


Set on Any Enabled VIC IRQ 
Condition 






3 


Light-Pen Triggered IRQ Flag 






2 


Sprite to Sprite Collision IRQ Hag 






1 


Sprite to Background Collision IRQ 
Flag 









Raster Compare IRQ Flag 


DOIA 


53274 




IRQ Mask Register: 1 = Interrupt 
Enabled 


DOIB 


53275 




Sprite to Background 
Display Priority: 1 = Sprite 


DOIC 


53276 




Sprites 0-7 Multi-Color Mode Select: 
1 = M.C.M. 


DOID 


53277 




Sprites 0-7 Expand 2 x Horizontal 

(X) 


DOIE 


53278 




Sprite to Sprite Collision Detect 


DOIF 


53279 




Sprite to Background Collision 
Detect 


D020 


53280 




Border Color 


D021 


53281 




Background Color 


D022 


53282 




Background Color 1 


D023 


53283 




Background Color 2 


D024 


53284 




Background Color 3 


D025 


53285 




Sprite Multi-Color Register 


D026 


53286 




Sprite Multi-Color Register 1 


D027 


53287 




Sprite Color 


D028 


53288 




Sprite 1 Color 


D029 


53289 




Sprite 2 Color 


D02A 


53290 




Sprite 3 Color 


D02B 


53291 




Sprite 4 Color 


D02C 


53292 




Sprite 5 Color 


D02D 


53293 




Sprite 6 Color 


D02E 


53294 




Sprite 7 Color 


D400-D7FF 


54272-55295 




MOS 6581 SOUND INTERFACE 
DEVICE (SID) 


D400 


54272 




Voice 1: Frequency Control— Low-Byte 


D401 


54273 




Voice 1: Frequency Control — High- 
Byte 


D402 


54274 




Voice 1: Pulse Waveform Width— 
Low-Byte 







u 




r 





u 
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n 



i \ 



n 
n 



n 
n 
n 



n 

n 



HEX 


DECIMAL 


BITS 


DESCRIPTION 


D403 


54275 


7-4 


Unused 






3-0 


Voice 1: Pulse Waveform Width— 
Higii-Nybble 


D404 


54276 




Voice 1: Control Register 






7 


Select Random Noise Waveform, 1 = 
On 






6 


Select Pulse Waveform, 1 = On 






5 


Select Sawtooth Waveform, 1 = On 






4 


Select Triangle Waveform, 1 = On 






3 


Test Bit: 1 = Disable OsciUator 1 






2 


Ring Modulate Osc. 1 with Osc. 3 
Output, 1 = On 






1 


Synchronize Osc. 1 with Osc. 3 
Frequency, 1 = On 









Gate Bit: 1 = Start Att/Dec/Sus, = 
Start Release 


D405 


54277 




Envelope Generator 1: Attack / Decay 
Cycle Control 






7-4 


Select Attack Cycle Duration: 0-15 






3-0 


Select Decay Cycle Duration: 0-15 


D406 


54278 




Envelope Generator 1: Sustain / 
Release Cycle Control 






7-4 


Select Sustain Cycle Duration: 0-15 






3-0 


Select Release Cycle Duration: 0-15 


D407 


54279 




Voice 2: Frequency Control— Low-Byte 


D40B 


54280 




Voice 2: Frequency Control — 
High-Byte 


D409 


54281 




Voice 2: Pulse Waveform Width— 
Low-Byte 


D40A 


54282 


7-4 


Unused 






3-0 


Voice 2: Pulse Waveform Width— 
High-Nybble 


D40B 


54283 




Voice 2: Control Register 






7 


Select Random Noise Waveform, 1 = 
On 






6 


Select Pulse Waveform, 1 = On 






5 


Select Sawtooth Waveform, 1 = On 






4 


Select Triangle Waveform, 1 = On 






3 


Test Bit: 1 = Disable OsciUator 2 






2 


Ring Modulate Osc. 2 with Osc. 1 
Output, 1 = On 






1 


Synchronize Osc. 2 with Osc. 1 
Frequency, 1 = On 









Gate Bit: 1 = Start Att/Dec/Sus, 
= Start Release 


D40C 


54284 




Envelope Generator 2: Attack / Decay 
Cycle Control 






7-4 


Select Attack Cycle Duration: 0-15 
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m, 




Commodore 64 Input/Output Assignments (continued) 


M» 




HEX 


DECIMAL 


BITS 


DESCRIPTION 


1 








3-0 


Select Decay Cycle Duration: 0-15 




D40D 


54285 




Envelope Generator 2: Sustain / 
Release Cycle Control 


\ 








7-4 


Select Sustain Cycle Duration: 0-15 


i—t 








3-0 


Select Release Cycle Duration: 0-15 






D40E 


54286 




Voice 3: Frequency Control — Low-Byte 


i 




D40F 


54287 




Voice 3: Frequency Control — 


\ 










High-Byte 




D410 


54288 




Voice 3: Pulse Waveform Width— 
Low-Byte 


n 




D411 


54289 


7-4 


Unused 


i t 








3-0 


Voice 3: Pulse Waveform Widtlt- 
High-Nybble 


O 




D412 


54290 




Voice 3: Control Register 










7 


Select Random Noise Waveform, 1 = 
On 


s^ 








6 


Select Pulse Waveform, 1 = On 










5 


Select Sawtooth Waveform, 1 = On 










4 


Select Triangle Waveform, 1 = On 








3 


Test Bit: 1 = Disable Oscillator 3 










2 


Ring Modulate Osc. 3 with Osc. 2 
Output, 1 = On 


1 
1j 








1 


Synchronize Osc. 3 with Osc. 2 










Frequency, 1 = On 













Gate Bit: 1 = Start Att/Dec/Sus, = 
Start Release 






D413 


54291 




Envelope Generator 3: Attack / Decay 
Cycle Control 


LJ 








7-4 


Select Attack Cycle Duration: 0-15 










3-0 


Select Decay Cycle Duration: 0-15 






D414 


54292 


7-4 


Envelope Generator 3: Sustain / 

Release Cycle Control 
Select Sustain Cycle Duration: 0-15 










3-0 


Select Release Cycle Duration: 0-15 






D415 


54293 




Filter Cutoff Frequency: Low-Nybble 
(Bits 2-0) 


... 




D416 


54294 




Filter Cutoff Frequency: High-Byte 






D417 


54295 




Filter Resonance Control / Voice 
Input Control 


i 








7-4 


Select FUter Resonance: 0-15 










3 


FUter External Input: 1 = Yes, = 
No 


LJ 








2 


Filter Voice 3 Output: 1 = Yes, = 

No 
Filter Voice 2 Output: 1 = Yes, = 

No 










1 
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HEX 


DECIMAL 


BITS 


DESCRIPTION 











FUter Voice 1 Output: 1 = Yes, = 

No 
Select Filter Mode and Volume 




D418 


54296 










7 


Cut-Off Voice 3 Output: 1 = Off, 
= On 








6 


Select Filter High-Pass Mode: 1 = 
On 








5 


Select Fater Band-Pass Mode: 1 = 
On 








4 


Select Filter Low-Pass Mode: 1 = On 








3-0 


Select Output Volume: 0-15 




D419 


54297 




Analog/Digital Converter: Game 
Paddle 1 (0^255) 




D41A 


54298 




Analog/Digital Converter: Game 
Paddle 2 (0-255) 




D41B 


54299 




Oscillator 3 Random Number 
Generator 




D41C 


54300 




Envelope Generator 3 Output 




DS00-D7FF 


54528-55295 




SID IMAGES 




D800-DBFF 


55296-56319 




Color RAM (Nybbles) 




DCOO-DCFF 


56320-56575 




MOS 6526 Complex Interface 
Adapter (CIA) #1 




DCOO 


56320 


7-0 

7-6 

4 

3-2 

3-0 


Data Port A (Keyboard, Joystick, 

Paddles, Light-Pen) 
Write Keyboard Cohinui Values for 

Keyboard Scan 
Read Paddles on Port A / B (01 = 

Port A, 10 = Port B) 
Joystick A Fire Button: 1 = Fire 
Paddle Fire Buttons 
Joystick A Direction (0-15) 




DCOl 


56321 


7-0 

7 

6 

4 

J-2 

3-0 


Data Port B (Keyboard, Joystick, 

Paddles): Game Port 1 
Read Keyboard Rove Values for 

Keyboard Scan 
Timer B: Toggle/Pulse Output 
Timer A: Toggle/Pulse Output 
Joystick 1 Fire Button: 1 = Fire 
Paddle Fire Buttons 
Joystick 1 Direction 




DC02 


56322 




Data Direction Register— Port A 

(56320) 




DC03 


56323 




Data Direction Registei^Port B 

(56321) 




DC04 


56324 




Timer A: Lovr-Byte 




DC05 


56325 




Timer A: High-Byte 




DC06 


56326 




Timer B: Low-Byte 
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Commodore 64 Input/Output Assignments (continued) 



u 



HEX 


DECIMAL 


BITS 


DESCRIKI'ION 


DC07 


56327 




Timer B: High-Byte 


DC08 


56328 




Time-of-Day Clock: 1/10 Seconds 


DC09 


56329 




Time-of-Day Clock: Seconds 


DCOA 


56330 




Time-of-Day Clock: Minutes 


DCOB 


56331 




Time-of-Day Clock: Hours + 
AM/PM Flag (Bit 7) 


DCOC 


56332 




Synchronous Serial I/O Data Buffer 


DCOD 


56333 




CIA Interrupt Control Register (Read 
IRQ's/Write Mask) 






7 


IRQ Flag (1 = IRQ Occurred) / 
Set-Clear Flag 






4 


FLAGl IRQ (Cassette Read / Serial 
Bus SRQ Input) 






3 


Serial Port Interrupt 






2 


Time-of-Day Clock Alarm Interrupt 






1 


Tbner B Interrupt 









Timer A Interrupt 


DCOE 


56334 




CIA Control Register A 






7 


Tnne-of-Day Clock Frequency: 1 = 
50 Hz, = 60 Hz 






6 


Serial Port I/O Mode: 1 = Output, 
= Input 






5 


Timer A Counts: 1 = CNT Signals, 
= System 02 Clock 






4 


Force Load Timer A: 1 = Yes 






3 


Timer A Run Mode: 1 = One-Shot, 
= Continuous 






2 


Timer A Output Mode to PB6: 1 = 
Toggle, = Pulse 






1 


Timer A Output on PB6: 1 = Yes, 

= No 









Start/Stop Timer A: 1 = Start, = 
Stop 


DCOF 


56335 




CIA Control Register B 






7 


Set Alarm/TOD-Clock: 1 = Alarm, 
= Clock 






6-5 


Timer B Mode Select: 

00 = Count System 02 Clock Pulses 

01 = Count Positive CNT 
Transitions 

10 = Count Timer A Underflow 
Pulses 

11 = Count Timer A Underflows 
WhOe CNT Positive 






4-0 


Same as CIA Control Reg. A— for 
Timer B 



n 
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HEX 



DDOO^DDFF 
DDOO 



DECIMAL 



56576-56831 
56576 



DDOl 



56577 



DD02 
DD03 
DD04 
DD05 
DD06 
DD07 
DD08 
DD09 
DDOA 
DDOB 

DDOC 
DDOD 



DDOE 



56578 
56579 
56580 
56581 
56582 
56583 
56584 
56585 
56586 
56587 

56588 
56589 



56590 



BITS 



7 
6 
5 

4 
3 
2 
1-0 



DESCRIPTION 



MOS 6526 Complex Interface 

Adapter (CIA) #2 
Data Port A (Serial Bus, RS-232, 

VIC Memory Control) 
Serial Bus Data Input 
Serial Bus Clock Pulse Input 
Serial Bus Data Ouput 
Serial Bus Clock Pulse Output 
Serial Bus ATN Signal Output 
RS-232 Data Output (User Port) 
VIC Chip System Memory Bank 

Select (Default = 11) 
Data Port B (User Port, RS.232) 
User / RS-232 Data Set Ready 
User / RS-232 Clear to Send 
User 

User / RS-232 Carrier Detect 
User / RS-232 Ring Indicator 
User / RS-232 Data Terminal Ready 
User / RS-232 Request to Send 
User / RS-232 Received Data 
Data Direction Register— Port A 
Data Direction Register — ^Port B 
Timer A: Low-Byte 
Timer A: High-Byte 
Tfaner B: Low-Byte 
Timer B: High-Byte 
Tune-of-Day Clock: 1/10 Seconds 
Tune-of-Day Clock: Seconds 
Time-of-Day Clock: Minutes 
Time-of-Day Clock: Hours + 

AM/PM Flag (Bit 7) 
Synchronous Serial I/O Data Buffer 
CIA Interrupt Control Register (Read 

NMI's/Write Mask) 
NMI Flag (1 = NMI Occurred) / 

Set-Clear Flag 
FLAGl NMI (User/RS-232 Received 

Data Input) 
Serial Port Interrupt 
Timer B Interrupt 
Timer A Interrupt 
CIA Control Register A 
Time-of-Day Clock Frequency: 1 = 

50 Hz, = 60 Hz 
Serial Port I/O Mode: 1 = Output, 

= Input 
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Commodore 64 Input/Output Assignments (continued) 



HEX 



DECIMAL 



DDOF 



56591 



DEOO-DEFF 
DFOO-DFTF 



BITS 



56832-57087 
57088-57343 



4 
3 

2 

1 



7 
6-5 



4-« 



DESCRIPTION 



Timer A Counts: 1 = CNT Signals, 

= System 02 Clock 
Force Load Timer A: 1 = Yes 
Timer A Run Mode: 1 = One-Shot, 

= Continuous 
Timer A Output Mode to PB6: 1 = 

Toggle, = Pulse 
Timer A Output on PB6: 1 = Yes, 

= No 
Start/Stop Timer A: 1 = Start, = 

Stop 
CIA Control Register B 
Set Alarm/TOD-Clock: 1 = Alarm, 

= Clock 
Timer B Mode Select: 

00 = Count System 02 Clock 
Pulses 

01 = Count Positive CNT 
Transitions 

10 = Count Timer A Underflow 
Pulses 

11 = Count Timer A Underflows 
While CNT Positive 

Same as CIA Control Reg. A— for 

Timer B 
Reserved for Future I/O Expansion 
Reserved for Future I/O Expansion 
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This chapter describes the Commodore C128 hardware, VLSI integrated circuit require- U 

ments, and the relationship between the hardware configuration and the operating 

system. | { 

The CI 28 personal computer is compatible with C64 software and peripherals. In [J 

addition to C64 compatibility, a C128 mode exists in which 128K of RAM is available 
for system/user use. BASIC version 7.0 is the default language. The Commodore Kemal , , 

is supported in a compatible fashion. { ( 

The C128 also has a Z80 coprocessor that can make full use of system RAM and ^ 

Kemal utilities, intended for use with such powerful operating systems as CP/M version 
3.0. The Banking ROM scheme allows function key software to be installed internal to | 

the system or added externally as an expansion cartridge. u 

Another major feature is the 8563 80-column display capability, available in CI 28 
mode as an addition to the 40-column mode. j \ 

Peripheral support includes the Commodore mouse, joystick, paddle, light pen ij 

interface (both 40- and 80-colunin light pens); the Commodore Datassette; the User Port, 
which supports RS232; modems; the Expansion Bus, which supports external memory 
expansion; and the Commodore standard Serial Bus, which supports all existing Serial j i 

Bus components. There are also several features intended to reduce software overhead, W 

such as relocatable zero page and system stack. 

In C64 mode, the standard sixty-six keys are available. In C128 mode, twenty- j 

six extra keys are available, including separate cursor keys, a HELP key, addi- jj 

tional function keys, and a true CAPS LOCK key. The additional keys, 
grouped into the alternate keypad, are user-definable, increasing the flexibility and user 
friendliness of the system. j 

The following is a summary of CI 28 features: 



C64 compatibility 

80-column display capability Uj 

Z80 coprocessor (CP/M version 3.0 (2 MHz)) 

2 MHz 8502 operation in 80-column mode 

128K standard system RAM 

48K standard system ROM 

32K internal function ROM (optional) 

32K external cartridge ROM 

Fast serial disk drive interface 

Full keyboard, ninety-two keys with CAPS LOCK key, HELP key 

and separate cursor-control keys. 
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The C128 computer utilizes a shared bus structure similar to that of the C64. The shared 
^ bus emulates dual-port RAM and ROM, which allows the character ROM, color RAM 

Pj and system RAM to be shared by both the microprocessor and the 8564 VIC video 

controller, with no interference to each other. This requires that the RAM be fast enough 
to supply valid data in half the time of a normal microprocessor machine cycle. Normal 
sharing is controlled by a coprocessor that will enable or disable the processor during 
alternate halves of the machine cycle. 

The CI 28 system splits the address bus into shared and nonshared sections. All 

^ normal 8502 I/O parts are on the nonshared address bus; the VIC chip and its associated 

j j support chips are located on the shared bus. The VIC chip will gate processor addresses 

onto the shared bus based upon its AEC control line. The data bus is common to both 

sides of the address bus. 

PI The processor interfaces with most of the system chips like a standard 6502 bus 

I \ cycle, where a machine cycle is equal to a clock cycle. This allows the use of 1 MHz 

parts for a 1 MHz clock and eliminates the need to create valid address and data strobes, 

r-| as this information is now supplied by the edges of the master clock, <I>0. Chip selects 

I [ for the I/O and system ROM are generated by the PLA fliat tracks the microprocessor 

addresses during <I>1. 

For system RAM access, the row address is the address from the microproces- 

P sor, and the column address is the MMU output address (called the Translated Address). 

I I The Translated Address outputs are calculated by considering the contents of the 

MMU's Configuration Register and RAM Configuration Register. From these values, 

m the MMU generates eitfier normal or translated addresses, a CAS selection. The 

[ { CAS-gating circuitry in the MMU enables either one of the two banks of 64K RAM in a 

128K system. For VIC cycle access of RAM, the RAM bank is set independently of the 

^ processor's bank. A write to ROM will result in the write "bleeding through" to RAM 

j j underneath, while a read from ROM will always disable CAS in both banks. The MMU 

' allows custom arrangements of RAM for both banks and 1 . 

Banking ROM is effected through the setting of bits in the Configuration Register 
"^ contained in the MMU and communicated to the PLA decoder. This allows Banking 

\ Function ROM and any attached CI 28 cartridge to be included in the basic system 

configuration. 

The PLA generates chip selects for the color RAM, VIC control registers and 
character ROM, which are used during processor and VIC cycles, as well as all chip 
selects needed for the processor-only ROM and peripherals. To avoid bus contention, 
the PLA must also generate CAS disable for any accesses to ROM or I/O devices. 

The VIC chip generates the signals used to control Dynamic Memory and provides 
macro-control functions such as RAM refresh. The VIC's primary purpose is to fetch 
screen data from memory, using either cycle sharing or DMA, and create an NTSC- or 
PAL-compatible video output that is applied to a monitor or modulated and applied to a 
TV set. The C128 provides outputs for Composite, Chroma/Luminance and RF video 
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SYSTEM SPECIFICATION 

This section discusses various features and constraints of the CI 28 system. Included are 
descriptions of the system and its configurations and limiting factors such as power, 
loading and environment. 

Figure 16-1 shows the C128 system. 








LJ 



u 



outputs from the VIC chip, as well as an edge-triggered light pen input latch going to 
the VIC chip. 

The output from the SID chip sound generator is buffered and applied directly to 
an external amplifier, like that found in an external monitor, or modulated and repro- 
duced in the user's television set. The SID chip also has an external input for mixing 
another sound source. \ j 

The 8563 video control chip fetches screen data from a dedicated section of RAM j j 

referred to as the display RAM and creates an RGBI (Red-Green-Blue-Intensity) output "-' 

for use with an external 80-column monitor. The 8563 also creates all needed signals for 
dynamic refresh of its dedicated display RAM. The C128 provides RGBI and composite 
monochrome outputs firom the 8563 chip. 

The cassette port is implemented using the zero page ports available on the 8502 
and software control of hardware handshaking. The Conmiodore serial bus port is imple- j i 

mented in a similar manner using a 6526 CIA for VO. The serial bus works with )J 

Commodore serial components, and in C64 mode is actually driven by the software 
routines contained in the C64. The User Port is a multipurpose port comprising several 
parallel port lines that support peripherals such as slow RS232, modem, etc. The 
joystick ports are identical to those on the C64 and are implemented using a 6526 CIA ^ 

to read/write the port. 

The video connector has composite video as well as separate chroma and lumi- 
nance outputs for use with monitors. The 1701 and 1702 Commodore monitors interface 
directly to this connector. The RF output jack supplies an RF signal compatible with the 
regulations for TV interface devices and is switch selectable between channels 3 and 4. ; , 

Both NTSC and PAL television standards are supported. The RGBI connector and ) 

signal are similar to the ones used by IBM, and are compatible with most monitors 
supporting Type I RGBI. Additionally, a composite monochrome signal is available on 
the RGBI connector and is generally compatible with NTSC (or PAL) composite. Audio | j 

is available only from the 40-column video/audio connector. u 
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Figure 16-1. The CI 28 System 
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SYSTEM BUS ARCHITECTURE 

The buses described include: 



Processor bus 
Translated address bus 
Multiplexed address bus 



Shared address bus 
Color data bus 
Display bus 



THE PROCESSOR BUS 

The Processor Bus includes the data and address buses that are connected directly to the 
8502 processor. These buses are designated D0-D7 for the 8-bit data bus and Aq-Au for the 
16-bit address bus. These buses tie the processor to most of the system ROM and I/O 
devices, including at least part of all system ROM, all built-in function ROM, the 
MMU, the PLA, the 8563 video processor, the SID and both CIA chips. 

The processor bus is in communication with the Z80 coprocessor as well. All 
address lines are shared directly by both processors. In order to allow the Z80 to operate 
on a 6502 family bus, it is necessary to latch data going into the Z80 and gate the data 
leaving the Z80. Thus, the Z80 has a small local data bus, designated ZD0-ZD7. During 
a write cycle, when AEC is high, Z80 data is gated to the processor bus. During a read 
cycle, processor bus data is gated to the Z80 data bus. This read data is transparently 
latched by the 1 MHz system clock. 



NOTE: Read and write cycles referred to in this document, unless 
otherwise specified, are 8502-type bus cycles. The Z80 Read Enable and 
Write Enable outputs are conditioned using logic to interface with an 
8502 bus cycle, so no distinction is made as to the differences between 
cycles of the different processors. For more information on this logic, 
consult the section on the Z80 processor and the CI 28 Schematic, 
Commodore Part No. 310378. 



As mentioned above, the Z80 is not in direct communication with the processor 
data bus, because of the need to adapt the Z80 to 8502 bus protocol. Note, however, 
that every other device and every other bus (except two that will be explained later) 
shares the processor data bus as a common data bus. 

THE TRANSLATED ADDRESS BUS 

Another CI 28 system bus is the Translated Address Bus produced by the MMU during 
AEC high. This bus consists only of high-order addressing lines, designated TAg-TAis. 
These lines reflect the action of the MMU on the normal high-order address lines, which 
may or may not include some sort of translation. The MMU can translate the address of 
page zero or page one in normal operation, and it translates the Z80 address from $0000 
through $0FFF in order to direct it to read the Z80 BIOS. A more complete description 
of MMU translations can be found in the MMU section of this document. 

Normally, the translated address bus indirectly drives the system RAM and the VIC 
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' chip by driving tlie multiplexed address buses. It directly drives system ROM 4 address 

line 12 to allow the Z80 ROM relocation. Finally, this bus becomes address lines 8 

^ through 15 of the C64 compatible expansion port. 

) { During a VIC cycle or a DMA, the MMU pulls TA,2-TAi5 high, while TAg-TA,, 

are tri-stated. This allows the VIC chip to drive TAg-TA,, as VIC addresses VAg-VA,,. 

r^ During an external DMA cycle, the TA lines of the MMU are tri-stated, and the TA 

/ { bus, presumably driven by the DMA source, in turn drives the processor address bus 

from Ag to Ai5. Thus allows the DMA source to access any peripheral chip except the 
MMU. The action of the VIC during a VIC cycle is described below. 

' ' THE MULTIPLEXED ADDRESS BUS 

This section describes two related address buses, the Multiplexed Address Bus and the 
n VIC Multiplexed Address Bus, known respectively as MA0-MA7 and VMA0-VMA7. 

/ 1 The VIC multiplexed address bus is created during AEC high by multiplexing the 

high-order translated address bus (TAg-TA, 5) with the low-order processor address bus 
(Aor-Av), controlled via the MUX signal. This bus, driven by a hardware multiplexer 
through series resistors, is called the Multiplexed Address Bus. The VIC multiplexed 
address bus is used for processor access of the VIC chip registers. It is also used for VIC 
access of system RAM. 

During a VIC cycle (AEC low), the VIC chip address lines will be asserted. There 
is no completely separate address bus for the VIC addresses, so it shares the VMA0-VMA7 
and address lines that are tri-stated during AEC high. Most of the VIC addresses come 
out of the VIC chip already multiplexed, but two of them, VAg and VA7, do not supply 
column information, as the VIC chip supplies only 14 bits of addressing. The higher- 
order address bits VA,4 and VA15 come from CLA-2, as in the C64. This means the VIC 
supplies complete VMA0-VMA7 for a VIC DRAM access or DRAM refresh. The 
TAg-TA,, supplied by VIC are used in conjunction with another addressing bus for 
nonmultiplexed VIC cycle addresses, such as character ROM and color RAM accesses. 

THE SHARED ADDRESS BUS 

The Shared Address Bus is a nonmultiplexed address bus used by both the processor 
and the VIC chip to communicate with common resources, namely the character ROM 
and color RAM (and the 8563 system RAM indirectly). During AEC high, the shared 
address bus, designated Sao-SA7, is driven by A0-A7, the lower-order processor 
address bits. The higher-order bits needed are supplied by the translated address bus, 
which is also a shared address bus. Thus, the processor is able to access both shared 
items. 

During AEC low, die VIC addresses VA0-VA7 (VMA0-VMA7) must come onto 
the shared address bus. Since VAo-VAg are actually multiplexed, the row address only 
must be sent to the shared address bus. Thus, the muhiplexed VIC addresses are 
transparently gated when either /RAS or MUX are high, but latched and held afterward 
so that when combined with the colunm address, the full address is presented. The high- 
order address bits here are supplied by the shared translated address bus. Note that the 
shared address bus provides the lower 8 bits of the expansion port address, allowing VIC 
access to cartridges and some additional drive capability by way of the TTL chips used to 
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drive the shared address bus. During DMA, the SA lines, like the TA, are driven '-^ 

backward to drive the processor bus. As noted above, this allows peripheral chips, ROM 

and RAM to be accessed by a DMA source, like the RAM expansion module. Only the j i 

MMU and the 8563 video controller cannot be accessed during DMA. See the auto-start u 

ROM section in Chapter 13 for more details on initializing both external and internal 

expansion ROMS. I i 

THE COLOR DATA BUS "^ 

The color RAM is written to or read from a nybble data bus called the Color Data Bus. 

During AEC high, the color data bus is connected to the lower half of the processor data \ j 

bus via an analog switch, allowing the processor full access to the color RAM. During w 

AEC low, that switch is opened, effectively isolating the color data bus from the 

processor data bus. In this state, it is driven by the VIC extended data bus Dg-Dn. | ( 

Since the color RAM is banked, only one-half appears here at a time. jj 

THE DISPLAY BUS ^ 

The Display Bus is a bus local to the 8563 video controller, consisting of the Display j 

Address (DAo-DA?) and the Display Data Bus (DDo-DD?). This local bus supports ^ 

the 8563 display RAM, which is completely isolated from the rest of the CI 28 system. 

The display address bus is a multiplexed address bus providing addressing to the display 1 I 

DRAM. The display data bus provides communication between this DRAM and the (J 

8563. The 8563 also provides row and column strobes and dynamic refresh to this 

DRAM. I I 

SYSTEM MEMORY ^ 

ORGANIZATION ^ , 

This section describes the C128 memory system. Figure 16-2 is a detailed diagram of Lj 
the C128 Memory Map. 
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Figure 16-2. CI 28 Memory Map (C64 Mode) 
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CI 28 ROM MEMORY ORGANIZATION 

C128 mode is achieved at system reset and is controlled by a bit in the MMU 

Configuration Register. In C128 mode, the MMU asserts itself in the C128 memory | 

map at $FFOO and in the I/O space, starting at $D500. Use of MMU registers located at l 

$FFOO allows memory management without actually having the I/O block banked in at 

the time and with a minimum loss of contiguous RAM. The MMU is completely ) 

removed from the memory map in C64 mode. It is, however, still used by the hardware 

to manage memory. 

Figure 1 6-2 presents the standard map for the C64 mode . Some of the alternate modes ^ 

are shown in Figure 16-3. All C64 modes are compatible with the C64 computer, as the \ j 

CI 28 basically becomes a C64 when in C64 mode. The details of MMU register '~' 

location/operation are discussed in Chapter 13. 

The ROMs in C64 mode look like Commodore 64 ROMs. The internal BASIC \ I 

and Kemal provide the C64 mode with the normal Conamodore 64 operating system in ij 

ROM. This ROM actually duplicates some of the ROM used in C128 mode, but it is 
necessary, as it is not accessible from C128 mode. In C128 mode, up to 48K of the ^ , 

operating system is present, with the exact amount being set by software control. This I 

allows quicker access to underlying RAM by turning off unneeded sections of the 
operating system. 

The external ROMs represented on the memory map are those used in C64 mode. j I 

They obey the Commodore 64 rules for mapping; i.e., cartridges assert themselves in Lj 

hardware via the /EXROM and /GAME lines. External ROMs in CI28 mode (i.e., C128 
cartridges) are mapped as banked ROMs; when the system is initialized, all ROM slots \ 

are polled for the existence of a ROM, and the ROM's priority, if one exists. This |_ 

allows much more flexibility than the hard-wired ROM substitution method, since the 
Kemal and BASIC ROMs can be swapped for an application program, or for external 
program control, or can be turned off altogether. This banking manipulation is accom- i j 

plished by writing to the Configuration Register at location $D500 or $FFOO in the '-' 

MMU. 

The hardware also features the ability to store preset values for the configuration } / 

and force a load of the Configuration Register by writing to one of the LCRs (Load U 

Configuration Registers). This allows the programmer to imply that ROM does not 
appear in the bank (by default) any time an access occurs to a bank where data is stored. . / 
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Figure 16-3. C64 Alternate Memory Configurations 
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CI 28 RAM MEMORY ORGANIZATION '-' 

As shown in Figure 16-2, the RAM present in the system is actually composed of two 

banks of 64K by 8 bytes of DRAM. The RAM is accessed by selecting one of the two 64K j j 

banks, the maximum address range of the 8502 and Z80, according to the RAM banking U 

rules set in the RAM configuration register of the MMU. This area shown as RAM 

represents what the processor would see if all ROM were disabled. Bank switching can | { 

be accomplished in one of two ways. ij 

The bank in use is a function of the value stored in the configuration register. A 
store to this register will always take effect immediately. An indirect store to this ^ ^ 

register, using programmed bank configuration values, can be accomplished by writing \ j 

to one of the indirect load registers known as LCRs, located in the $FFOO region of '^ 

memory. By writing to an LCR, the contents of its corresponding PCR (PreConfiguration 
Register) will be latched into the configuration register. This allows the programmer to j < 

set up four different preprogrammed configurations that allow each bank to be personal- lJ 

ized ahead of time; e.g., bank 1 as a data bank might be strictly a RAM bank with no 
ROM or I/O enabled, while bank as the system bank can have the system ROM and , i 

I/O enabled by default. Additionally, reading any LCR will return the value of its M 

corresponding PCR. 

When dealing with 64K banks of memory at once, it may be desirable to bank in 
bank 1 but still retain the system RAM (stack, zero page, screen, etc.). The MMU has 
provisions for what is referred to as conunon RAM. This RAM does not bank and is U 

programmable in size and position (top, bottom, or both) in the memory map. The size 
is set by bits and 1 in the RAM Configuration Register (RCR). If the value of the \ 

bits is 0, IK will be common. Values of 1 , 2 and 3 produce common areas of 4K, 8K 
and 16K respectively. If bit 2 of the RCR is set, bottom memory is held common; if bit 
3 is set, then top memory is common. In all cases, common RAM is physically located ^ 

in bank 0. \ 

Zero page and page one can be located (or relocated) independently of the *■ 

RCR. When the processor accesses an address that falls within zero page or page 
one, the MMU adds to the high-order processor address the contents of the PO 
register pair or the PI register pair, respectively, and puts this new address on the '■ 

bus, including the extended addressing bit A16. RAM banking will occur as appropriate 
to access the new address. Writes to the PO and PI registers will be stored in pre- \ 

latch until a write to the respective low byte page pointer occurs. This prevents a Pxh t 

high byte page pointer from affecting the translated address until both high and low 
bytes have been written. Common memory overrides the page pointers. j 

At the same time, the contents of the PO and Pl registers are applied to a digital [ 

comparator, and a reverse substitution occurs if the address from the 8502 falls within 
the page pointed to by the register. This results in a swapping of the zero page or page . 

one with the memory that it replaced. Swapping occurs only if the swapped area is 
defined as RAM; i.e., system or function ROM must always be at its assigned addresses 
and thus should not be back-substituted but of course will not cause contention of any 
kind. Note that upon system reset, the pointers are set to true zero page and true page 
one. 
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NOTE: There are actually several memory modes that override parts of 
the bank as selected here. These modes are mentioned below, and are 
covered in detail in a later section. 



I i 



For VIC-chip access, one bit in the MMU status register substitutes for extended 
address line Aig, selecting the proper CAS enable to make it possible to steer the VIC 
to anywhere in the 128K range. Note that AEC is the mechanism the MMU uses to steer 
a VIC space address; i.e., when AEC is low, a VIC access is assumed. This results in 
the VIC bank being selected as well for an outside DMA, since this, too, will pull the 
AEC line to the MMU low. 
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PERFORMANCE SPECIFICATIONS 

POWER CONSUMPTION 

Table 16-1 contains values for C128 power consumption, including various add-on 
options. 



I.C. 



Ii>p I 

(5v) 



Max 



I Typ I Max I Typ * Max 

(9v) (12v) 



Unit 



SUBTOTAL 



61 2.63 3.83 0.03 0.05 









PERIPHERALS 


















—1 


Magic Desk 


1 


0.24 


0.35 














A 


RS-232 


1 


0.07 


0.10 














A 




Auto Modem 


1 








0.07 


0.10 








A 


r~i 


Cassette 


1 








0.28 


0.40 








A 


I 

i 


PERIPHERAL TOTAL 


4 


0.31 


0.45 


0.35 


0.50 








A 




C128 AND PERIPHERALS 




2.94 


4.28 


0.38 


0.55 








A 



( 1 

i i 



n 



TOTAL POWER, WORST CASE (WATTS) 

SV 12V 
Voltage 5.25 9.45 12.60 total 
Power 22.47 5.20 0.00 27.67 



Table 16-1. CI 28 Power Consumption 



BUS LOADING 

Table 16-2 details AC and DC device loading for the C128 system. All capacitances 
are in picofarads and currents are in microampheres. 
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DRAM ROM VIC 8563 4016 2332 LS MMU PLA 8502 Z80 4066 SID TOTAL 

TTL CIA LOADS 



Dev: 
Signal 



TA8-TA,s 
# 
I 

C 

SAq-SA? 

# 

I 

c 

Do-D, 
# 
I 

c 

R/W 
# 
I 

c 

RES 
# 
I 

c 

IMHz 
# 
I 

c 



2 
20 



1 1 

10 2.5 
8 8 



5 

50 
40 



1 

2.5 
8 



1 

■- 2.5 
- 8 



1 

2.5 
8 

1 

2.5 
8 

1 

2.5 
8 



1 1 2 

10 10 800 

4 8 30 

1 1 1 

10 10 400 

4 8 15 

1 

400 

15 

2 

800 

30 



5 
2000 

75 



1 

2.5 
8 

1 

2.5 
8 

1 

2.5 
8 



1 

2.5 
8 



1 

2.5 
8 

1 

2.5 
8 



1 
.. 0.1 

- 8 



1 

... 2.5 
.. 8 



1 

2.5 
8 



3 

7.5 

24 

3 

7.5 
24 

3 

7.5 
24 

3 
7.5 
24 



833 
58 



420 

27 



488 
129 



820 
94 



18 
56 



2008 
99 



u 
u 



u 



u 



Table 16-2. Bus Loading Power Requirements (Capacitances and Currents) 

ENVIRONMENTAL SPECIFICATIONS 

The C128 is rated to operate at from 10 to 40 degrees Celsius (50 to 104 degrees 
Fahrenheit) and at a noncondensing relative humidity of 5 to 95 percent. 
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THE 8502 
MICROPROCESSOR 

GENERAL DESCRIPTION 

The 8502 is an HMOSII Technology microprocessor, similar to the 6510/6502. It is the 
normal operating processor used in C64 and CI 28 modes. Software-compatible with 
the 6510, hence the 6502, the 8502 also features a zero page port used in memory 
management and cassette implementation. 

The 8502 is also specified for operation at 2 MHz. The 2 MHz operation is made 
possible by removing the VIC from the system as a display chip. (The VIC chip is never 
completely removed from the CI 28 system, as it continues to function as clock 
generator and refresh controller.) What this refers to is that the VIC is removed as a display 
chip and co-processor; thus the full clock cycle can be devoted to processor functioning 
instead of sharing the cycle with the VIC. 

The task of the video display processor is taken over by the 8563, which can 
function without the need for bus sharing. Since the I/O devices, SID, etc., are rated at 
1 MHz only, stretching of the 2 MHz clock is used to allow these parts to be accessed 
directly by the 2 MHz processor and still keep throughput to a maximum. 

The I/O devices are not affected by the 2 MHz operation, as they are still driven 
by a 1 MHz source (as such, all timer operations remain unchanged), and clock 
stretching is used only to synchronize the 2 MHz machine cycle to the 1 MHz 4>0 high 
time. The clock sources and clock-stretching capabilities are generated by the VIC chip. 

ELECTRICAL SPECIFICATION 

This section describes some of the electrical constraints and specifications of the system. 

MAXIMUM RATINGS 

Table 16-3 gives the absolute maximum ratings of the 8502 microprocessor. 



RATING 

Supply Voltage 
Input Voltage 
Storage Temperature 
Operating Temperature 


SYMBOL 

Vcc 

v,„ 

Ta 


VALUE 

-0.5 to +7.0 
-0.5 to +7.0 
-55 to +150 
Oto +70 


UNIT 

Vdc 
Vdc 
"C 



Table 16-3. 8502 Absolute Maximum Ratings 

ELECTRICAL CHARACTERISTICS 

Table 16-4 gives the 8502's basic electrical specifications for minimum, typical and 
worst-case operation, valid over the range of operation T. 
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CHARACTERISTIC 


SYMBOL 


MIN 


TYP 


MAX 


UNIT 


Input High Voltage 
<}>o(in) 
/RES, Po-P7,/IRQ, Data 


Vni 


V,s + 2.4 
V« + 2.2 


I 


Vcc 


Vdc 
Vdc 


Input Low Voltage 
<l>o (in) 
/RES, Po-P7,/IRQ, Data 


Vn. 


V,s-0.3 


— 


V^ + 0.5 
Vss + 0.8 


Vdc 
Vdc 


Input Leakage Current 

(Vto = to 5.25V, Vcc= 5.25V) 

Logic 

<|)o(in) 


Im 


— 


— 


2.5 
10.0 





3-State (Of!) Inp. Cur. Itoi 

(Vto = 0.4 to 2.4V, V„= 5.25V) 
Data Lines 

Output Higli Voltage Vqh 

aoH=-100M,Adc, V„ = 4.75V) 
Data, Ao-Ais, R/W, PtrP? 

Output Low Voltage 
(loL = l.fimAdc, V„ = 4.75V) 
Data, Ar-Ais, R/W, Po-Pt 

Power Supply Current Ice 

Capacitance C 
(V|„ = 0,T,=25C,f=lMHz) 

Logic, Po-Pt Ch, 

Data Cout 

AflT-Av Cout 

<t>o C<t>o 



— 10.0 



(JiA 



V,s+2.4 — 


■■■" 


Vdc 


^^ ^^ 


Vs, + 0.4 


Vdc 


— 125 


— 


niA 


— 30 


10 
15 
12 
50 


pF 
pF 
pF 
pF 



u 

U 

t i 

u 

u 

\ I 

u 



Table 16-4. 8502 Basic Electrical Specifications 



I 

U 

U 
U 



SIGNAL DESCRIPTION 

Below is a description of all the 8502 signals from a functional and electrical point of 
view: 

CLOCK (Oo) — ^This is the dual speed system clock. Note that the input level required is 

above worst-case TTL; thus, extra precautions must be taken when attempting to 

drive this input from a standard TTL level input. 
ADDRESS BUS (A0-A15)— TTL output. Capable of driving 2 TTL loads at 

130 pF. 
DATA BUS (Dff-Dr) — ^Bidirectional bus for transferring data to and from the device 

and the peripherals. The outputs are tri-state buffers capable of driving 2 standard 

TTL loads at 130 pF. 



n 
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RESET — ^This input is used to reset or start the processor from a power down 
condition. During the time that this line is held low, writing to or from the 
I I processor is inhibited. When a positive edge is detected on the input, the 

I ! processor will immediately begin the reset sequence. After a system initialization 

time of 6 cycles, the mask interrupt flag will be set and the processor will load the 
n program counter from the contents of memory locations $FFFC and $FFFD. This is 

I { the start location for program control. After Vcc reaches 4.75 volts in a power up 

routine, reset must be held low for at least 2 cycles. At this time the R/W line will 
become valid. 
INTERRUPT REQUEST (IRQ)— TTL input; requests that the processor initiate an 
interrupt sequence. The processor will complete execution of the current instruc- 
tion before recognizing the request. At that time, the interrupt mask in the Status 
Code Register will be examined. If the interrupt mask is not set, the processor will 
begin an interrupt sequence. The Program Counter and the Processor Status 
Register will be stored on the stack and the interrupt disable flag is set so that no 
other interrupts can occur. The processor will then load the program counter from 
the memory locations $FFFE and $FFFF. 
NON-MASKABLE INTERRUPT REQUEST (NMI)— TTL input, negative edge 
sensitive request that the processor initiate an interrupt sequence. The processor 
will complete execution of the current instruction before recognizing the request. 
The Program Counter and the Processor Status Register will be stored on the 
stack. The processor will then load the program counter from the memory 
locations $FFFA and $FFFB. Since NMI is non-maskable, care must be taken to 
insure that the NMI request will not result in system fatality. 
ADDRESS ENABLE CONTROL (AEC)— The Address Bus is only valid when the 
-1 AEC line is high. When low, the address bus is in a high impedance state. This 

allows DMA's for dual processor systems. 
I/O PORT (P«-P«)— Bidirectional port used for transferring data to and from the 
processor directly. The Data Register is located at location $0001 and the Data 
Direction Register is located at location $0000. 
R/W — ^TTL level output from processor to control the direction of data transfer between 
the processor and memory, peripherals, etc. This line is high for reading memory 
and low for writing. 
RDY — ^Ready. TTL level input, used to DMA the 8502. The processor operates 
normally while RDY is high. When RDY makes a transition to the low state, the 
~! processor will finish the operation it is on, and any subsequent operation if it 

is a write cycle. On the next occurrence of read cycle the processor will halt, 
making it possible to gain complete access to the system bus. 

PROCESSOR TIMING 

This section explores the timing considerations of the 8502 processor unit. Table 16-5 is- 
a processor timing chart. Figure 16-4 presents timing diagrams that show both general 
timing and the particular method of clock stretching used in 2 MHz mode. 
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Electrical Characteristics ¥„ = 5v ± 5%, V,, = Ov, T^ = T to 70 °C 



CHARACTERISTIC 


SYMBOL 


MIN 


MAX 


UNITS 


AEC setup time 


Taet 


25 


60 


ns 


Up data setup from 4>o 


Tmds 




100 


ns 


Up write data hold 


Thw 


40 




ns 


Data bus to tri-state from AEC 


Taedt 




120 


ns 


Read data stable 


Tdsu 


40 




ns 


Read data hold 


Thr 


40 




ns 


Address setup from <j)0 


Tads 


40 


75 


ns 


Address hold 


Tha 


40 




ns 


Address setup from AEC 


Taads 




60 


ns 


Address tri-state from AEC 


Taeat 




120 


ns 


Port input setup 


TpDSU 


105 




ns 


Port input half 


TpDH 


65 




ns 


Port output data valid 


TpDW 




195 


ns 


Cycle time 


TcYC 


489 




ns 


<|)0 (in) pulse width @1.5v (crystal clock) 


PWH*© 


235 


265 


ns 


<|>o (in) rise time 


TR4>o 




10 


ns 


4)0 (in) fall time 


TF<^o 




10 


ns 


RDY setup time 


Trdy 


80 




ns 



u 



u 
u 



Table 16-5. Processor Timing Chart 



u 



CLOCK STRETCHING 

When running in 2 MHz mode, the processor clock sometimes must be stretched. This 
is handled by the VIC chip, the processor and the FLA working together. When an I/O 
operation is decoded during a 2 MHz cycle, the phase relationship between the 2 MHz 
and 1 MHz clocks must be considered. If the 2 MHz access occurs during IMHz 4>1, the 
access to a clocked I/O chip would be out of synchronization with the 1 MHz clock that 
drives all I/O chips. Thus, during this phase relationship, /lOACC from the FLA signals 
the VIC chip to extend the 2 MHz clock. Should the 2 MHz cycles take place during the 
1 MHz <J>2 cycle, no special attention is necessary. 
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Figure 16-4. Clock Stretching in 2 MHz Mode 
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Note the speed implications of this. In 2 MHz mode, half the I/O access given will 
occur at an effective speed of IMHz. 

Figure 16-5 is a diagram of the 8502 microprocessor pin configuration. 
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Figure 16-5. The 8502 Microprocessor Pin Configuration 

For information on programming 8502 Machine Language, see Chapter 5, Machine 
Language on the CI 28. 



Z80 MICROPROCESSOR 
HARDWARE SPECIFICATION 



U 



The Z80 microprocessor is used as a secondary processor in the CI 28 to run CP/M 
based programs. Covered in this section is not only the operation of the Z80 as part of 
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the C128 system, but some important electrical and timing specifications of the Z80. For 
more information on Z80 bus interfacing, consult the Zilog Z80 Data Book. 

SYSTEM DESCRIPTION 

J-] The Z80A, a 4MHz version of Zilog's standard Z80 processor, is included as an 

I j alternate processor in the C128 system. This allows the C128 to run the CPM 3.0 

operating system at an effective speed of 2 MHz. The Z80 is interfaced to the 8502 bus 
interface and can access all the devices that the Z80 can access. The bus interface for the 
j I Z80 (the most complex part of the Z80 implementation) is described in this section, 

' ' along with Z80's operation as a coprocessor in the C128 system. 



NOTE: See the Signal Description section later in this chapter for 
definitions of the signals mentioned in the following paragraphs. 



BUS INTERFACE 

Because a Z80 bus cycle is much different than a 65xx family bus cycle, a certain 
amount of interfacing is required for a Z80 to control a 65xx-type bus. Since the Z80 
has built-in bus arbitration control lines, it is possible to isolate the Z80 by tri-stating its 
address lines. Thus, both the Z80 and the 8502 share common address lines. 

The interfacing of the data lines is more complex. Because of the shared nature of 
the bus during Z80 mode, the Z80 must be isolated from the bus during AEC low. Thus, 
a fri-statable buffer must drive the processor bus during Z80 data writes. The reverse 
situation occurs during a Z80 read— the Z80 must not read things that are going on 
during AEC low; it must latch the data that was present during AEC high. Thus, a 
transparent latch drives the data input to the Z80. It is gated by the Z80 read-enable 
output, and latched when the 1 MHz clock is low. It will be seen that the Z80 actually 
runs during AEC low, but that the data bus interfaces with it only during AEC high. 

CONTROL INTERFACE 

The Z80 control read-enable interfacing must provide useful clock pulses to the Z80, 
and must tailor the Z80 and write-enable signals for the 8502-type bus protocol. The 
Z80 clock is provided by the VIC chip, and is basically a 4MHz clock that occurs only 
during AEC low, as seen in Figure 16-6. This ensures fliat the Z80 is clocked only when 
it is actively on the bus. One additional consideration in clocking the Z80 is that while 
all of the 8502 levels and most of the Z80 levels are TTL-compatible, the Z80 clock 
input expects levels very close to 5 volts. For that reason, the output from the VIC chip 
is processed by the 9-volt supply; thus, the 9-volt circuit must be operational for the 
Z80, and the system, to function. The most common power-up failure for the C128 is a 
blown 9-volt fuse. 
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Figure 16-6. Z80 Bus Timing 
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PROCESSOR SWITCHING 

It is important in normal operation for the Z80 and the 8502 to operate as coprocessors, 1 

communicating with each other. Since only one processor may have the bus at any one 

time, this is only serial coprocessing, not parallel coprocessing or multiprocessing. This 

is important in several ways: { I 

First, the CI 28 system must power-up with the Z80 as master processor. This is to U 

prevent the Z80 from accidentally accessing the bus when powering up. Thus, the Z80 
is made master on power-up and can do anything it likes to the bus. Also, because the i j 

Z80 can start-up certain C64 applications that would cause the 8502 to crash, the Z80 is jj 

the logical choice as start-up processor. After some initializations, the Z80 starts-up the 
8502 in either CI 28 or C64 mode, depending upon whether a cartridge is present, and 
upon the type of cartridge, if one is present. The operating system also allows C64 mode 
to be forced on power-up. '— ' 

Second, processor switching allows the Z80 to access 8502 Kemal routines. For 
standardized programs or for any I/O operation not supported in the Z80 BIOS, the Z80 | 

can pass on the task of I/O to the 8502. Since the Z80 sees BIOS ROM where the 8502 jJ 

sees its pages through F, the Z80 can operate without fear of disrupting any 8502 
pointers or the stack in RAM Bank 0. The Z80 ROM BIOS physically overlays that 
critical section of RAM Bank 1 . 

The Z80 can receive a bus grant request from the MMU via /Z80EN, or from the 
VIC chip via BA. Since the VIC control line is used for DMAs, the latter request is not 
of immediate concern. The /Z80EN action, however, is important, since it is the i 

mechanism by which the two processors exchange control. L 
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When the /Z80EN line goes high, it triggers a Z80 /BUSRQ. The Z80 then relin- 
quishes the bus by pulling /BUSACK low. This action drives the 8502 AEC high and 
(providing VIC does not request a DMA) also drives the 8502 RDY line high, enabling 
the 8502. To switch back, a low on the Z80 /BUSRQ will result in Z80 /BUSACK 
going high, tri-stating and halting the 8502. 

See Appendix K on CP/M for interchip communication details. 

SIGNAL DESCRIPTION 

The hst below defines each Z80 signal. The Z80 pin configuration is shown in Figure 16-7. 

Address Bus (Agr-Ais): 16-bit tri-stating address bus. Used for 16-bit I/O cycles. This 
allows up to 256 input or 256 output ports. During refresh time, the lower 7 bits 
contain a valid refresh address. (This signal is not used in the C128 system.) 

Data Bus (D0-D7): Input/output bus capable of tri-stating; used for 8-bit exchanges 
with memory and I/O devices. 

Machine Cycle One (/M|): Output, active low. This signal indicates that the current 
machine cycle is the operation code fetch of an instruction execution. During 
execution of a two-byte opcode, /M, is generated, as each byte is fetched. /Mi also 
occurs with an input/output request (/lORQ) to indicate an interrupt acknowledge 
cycle. The Mi line is used to disable the I/O decoder during an interrupt acknowl- 
edge cycle (See Input/Output Request). 

Memory Request (/MREQ): Active low, tri-state output that indicates that the address 
bus holds a valid address for a memory read or write operation. 

Input/Output Request (/INRQ): Active low, tri-state output. The /INRQ signal 
indicates that the lower half of the address bus holds a valid address for an I/O 
read or write operation. An /INRQ signal is also generated with a /Mi signal when 
an interrupt is being acknowledged to indicate that an interrupt response vector 
can be placed on the data bus. An interrupt can acknowledge during /Mi; I/O 
operations never occur during /Mi. 

Memory Read (/RD): Active low, tri-state output. /RD indicates that the CPU wants 
to read data from memory or firom an I/O device. This signal is generally used to 
gate-read data onto the data bus. 

Memory Write (/WR): Active low tri-state output. /WR indicates that the data bus 
holds valid data to be processed by memory or by an I/O device. 

Refresh (/RFSH): Active low output used to indicate that the address bus holds a 
refresh address in its lower 7 bits. Thus, the current /MREQ signal should be used 
to do a refresh read to all dynamic memories not refreshed from an alternate source. 
A7 is set to and the upper 8 bits contain the I register at this time. 

Halt State (/HALT): Active low output, indicating that the Z80 has executed a halt 
instruction and is awaiting some kind of interrupt before execution can continue. 
While in the halt state, the Z80 continuously executes NOPs to continue refi-esh 
activity. 

Walt (/WAIT): Active low input, used to drive the Z80 into wait states. As long as this 
signal is low, the Z80 executes wait states; thus, this signal can be used to access 
slow memory and I/O devices. 
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NOTE: While the Z80 is in either a wait state or a bus acknowledge 
(/BUSAK) state, a dynamic memory refresh cannot be performed. See Bus 
Acknowledge. 



Interrupt Request (/INT): Active low input, driven by external devices. If the * / 

interrupt flag IFF is enabled and the bus request (/BUSRQ) line is not active, the |J 

processor honors the request interrupt at the end of the current instruction. When 
the Z80 acknowledges an interrupt, it generates an interrupt acknowledge signal 
(/INRQ during /Mi) at the beginning of the next instruction cycle. There are three M 

different modes of response to a given interrupt. See Bus Request. ^ 

Non-Maskable interrupt (/NMI): Active low input. This interrupt is edge-triggered 

and cannot be masked against. It is always recognized at the end of the current j j 

instruction, forcing the Z80 to restart at location $0066. The program counter is Ij 

automatically saved in the stack to allow a return from the interrupt program. Note 
that continuous cycles can delay an /NMI by preventing the end of the current r 

cycle, and that /BUSRQ will override /NMI. [ 

Reset (/RESET): Active low input that forces the program counter to zero and 
initializes the Z80, which will set interrupt mode 0, disable interrupts, and set 
register I and R to 0. During /RESET, the address and data buses go tri-state and j j 

all other signals go inactive. '-' 

Bus Request (/BUSRQ): Active low input that requests the CPU address, data and 
tri-statable output control signals to go tri-state for sharing and DMA's. The lines 
go tri-state upon termination of the current machine cycle. 

Bus Acknowledge (/BUSAK): Active low output, used to indicate to any device 
taking over the bus that the Z80 has gone into tri-state and the bus has been 
granted. | I 

Clock (<()): Single phase system clock. '-^ 
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Figure 16-7. Z80 Microprocessor Pin Configuration 



ELECTRICAL SPECIFICATIONS 

ABSOLUTE MAXIMUM RATINGS 

Table 16-6 gives the absolute maximum temperature, voltage and power dissipation 
ratings for the Z80. Permanent damage is likely to occur if these ratings are exceeded. 
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PARAMETER SYMBOL RANGE UNITS 

Operating Temperature T, to +70 °C 

Storage Temperature Ts, -65 to + 150 "C 

Input Voltage Vu, -0.3 to 7.0 Vdc 

Power Dissipation ?„ " 1.5 W 

Table 16-6. Z80 Absolute Maximum Ratings 



PARAMETER 


SYMBOL 


RANGE 


UNITS 


Power Supply Variance 


Vc. 


5 ± 5% 


Vdc 


Clock Input Low Voltage 


Vac 


-0.3 to 0.8 


Vdc 


Clock Input High Voltage 


V,HC 


Vcc-0.6toVcc + 0.3 


Vdc 


Input Low Voltage 


Vn. 


-0.3 to 0.8 


Vdc 


Input High Voltage 


Vffl 


2.0 to Vec 


Vdc 


Output Low Voltage 


Vol 


Vs, to 0.4 


Vdc 


aoL=1.8niA) 








Output High Voltage 


VoH 


2.4 to Vcc 


Vdc 


(IoH=-250|xA) 








Power Supply Current 


Ice 


200 


mA 


Input Leakage Current 


Ili 


10 


,xA 


(Vto = OtoVcc) 








Tri-State Leakage Current 


Ilo 


+ 10,-10 


fiA 


(VouTVoH,Voirr = VoL) 








Data Bus Input Leakage Current 


Ild 


±10 


f.A 


(V« s Vta s v„) 









Table 16-7. Z80 DC Operating Characteristics 

CAPACITANCE 

The line capacitance values for the Z80 are given in Table 16-8. All measurements are 
at T = 25 degrees, F = 1 MHz. 
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DC OPERATING CHARACTERISTICS | | 

Table 16-7 shows the maximum DC operating ratings for the Z80. Except as noted, Li 

these ratings apply over the full rated temperature and voltage ranges. 
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PARAMETER SYMBOL MAXIMUM UNIT 

Clock Capacitance C<t> 35 pF 

Input Capacitance Ci„ 5 pF 

Output Capacitance Cout 10 pF 

Table 16-4. Z80 Capacitance Values 
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THE PROGRAMMED 
] LOGIC ARRAY (PLA) 

The 8721 CI 28 PLA is a programmed version of the Commodore 48 Pin Programmable 
I Logic Array (Commodore Part #315011). It provides all the chip selects and other 

I decoded signals that are necessary for the C64, along with a number of such signals 

new in the C128 system. Figure 16-8 shows the PLA chip. 
, The PLA does a number of things vital to the operation of the CI 28, including: 

I 

■ All ROM selects (Kemal, BASIC, function, external) in all operating modes. 

■ VIC chip select. 

i ■ Color RAM chip select. 

i ■ Character RAM chip select. 

■ Write enable to color RAM. 

, ■ Latched write enable to DRAMs. 

j ■ Z80 select decoding. 

' ■ Z80 I/O decoding, for Z80 I/O cycle and Z80 memory mapping. 

■ Data bus direction signal. 

I ■ I/Ogroupchipselect(includesI/0-l, 1/0-2, CIA-l,CIA-2, SID, 8563). 

I ■ I/O access signal indicating an I/O operation is occurring. 

■ CAS ENaBle for DRAM enable. 

i CHIP SELECT GENERATION 

This PLA device is responsible for defining the banking rules for ROM and RAM that 
, the system will follow. This chip generates chip selects for all ROM and the VIC chip. 

I It generates an enable for any other I/O device in the map, and can enable or disable 

CAS based upon what else is enabled. In C128 mode, decisions are made using the 
processor addresses and the four mode status lines: ROMBANKLO, ROMBANKHI, 
I I/O SELECT, and C128/64. The C128 mode banking scheme is quite straightforward 

I and simple. In Z80 mode, the selection mechanism becomes even simpler, thanks to the 

I/O cycle of the Z80 processor. 
I C64 chip selects account for the bulk of the PLA font. The C64 selects I/O, RAM 

and ROM based upon internal control lines: BA, HIRAM, LORAM, and CHAREN. 
The status of these lines, and decoded addresses, determine for any given time which (if 
any) chip is selected. When a cartridge is inserted, two additional control lines come 
into play: /EXROM and /GAME. Various combinations of these lines cause different 
memory maps to be asserted, all based upon the PLA font. 

OTHER FUNCTIONS 

The PLA performs a variety of functions other than chip selects. It creates the write 
enable strobes for both DRAM and Color RAM. In C128 mode, the C64 control lines 
(HIRAM, LORAM and CHAREN) are not needed, since the MMU controls the more 
sophisticated CI 28 method of banking. Thus, these lines are used to extend the 
functionality of the C128 at little or no additional cost in hardware. The CHAREN line is 



582 COMMODORE 128 



used in CI 28 mode to turn the Character ROM on and off in the VIC bank selected; in 
C128 mode the ROM can appear or disappear in any VIC bank. 

The second of the new functions uses LORAM and HIRAM to select one of two 
Color RAM banks. The level of LORAM selects the bank that will be seen during 
processor time; the level of HIRAM selects the bank that will be seen during VIC time. 
Thus, a program can swap between two full-color pictures very cleanly, or the processor 
can modify one full-color picture while displaying another. 
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Figure 16-8. The CI 28 PLA Chip 
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THE MEMORY 
p MANAGEMENT UNIT (MMU) 

The MMU is designed to allow complex control of the C128 system memory resources. 
n Because of the way it handles all the standard C64 modes of operation, it is completely 

I 1 compatible with the C64. Additionally, it controls the management of particular C128 

modes including the Z80 mode. The MMU's features include: 

I [ ■ Generation of translated address bus (TA8-TA15). 

■ Generation of control signals for different processor modes (C128, C64, Z80). 

^ ■ Generation of CAS selects lines for RAM banking. 

j j ■ Generation of ROMBANK lines for ROM banking. 

Programming the MMU is described in detail in Chapter 13. 

i i PHYSICAL DESCRIPTION 

^ Many of the MMU input and output signals have been discussed informally so far. 

I j This section contains descriptions of the MMU as a physial 48-pin device, includ- 

ing a description of all pin requirements, input and output signals, and electrical 
requirements. 

I PIN REQUIREMENTS 

Table 16-9 lists the required MMU pins, indicating the number in each signal category 
—' and the total number. 
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SIGNAL NAMES 


DESCRllTION 


NUMBER OF PINS 


Aor-As, Ag-Ais 


Address Lines In 


12 


A4/5, A«/7 


Combined Address Lines In 


2 


D0-D7 


Data Lines In/Out 


8 


TAg-TAis 


Translated Addr. Lines Out 


8 


Vcc 


+ 5V 




GND 


Ground 




Pfflo 


2 MHz <{>„ Clock In 




RESET 


System Reset In 




RAV 


ReadAVrite Line In 




/CAS0-/CAS1 


DRAM CAS, 64K Bank Out 




AEC 


Address Enable Control In 




/Z80EN 


Z80 Enable Out 




/GAME 


Game ROM Enable In, Control Out 




/EXROM 


External ROM Enable In, Control Out 




MSp-MSi 


Memory Status Out 




I/O (MS2) 


I/O Select Out 




C128/64 (MS3) 


C128 or C64 Mode Out 




40/80 


40/80 Status In 




/FSDIR 


Fast Serial Direction Out 




MUX 


Memory Multiplex In 






TOTAL 


48 







Table 16-9. MMU Pin Requirements 

PIN DESCRIPTION 

The following comprises a signal-by-signal description of the MMU input and output 
signals. Figure 16-9 shows the MMU pin configuration. Included here are any available 
bond options. 

Tlie MMU input signals are: 

■ A0-A3, A8-A15: Addresses from the microprocessor. Used to derive chip 
selects as well as multiplexed address lines. A0-A3 are found at pins 18-21 on 
the MMU, while Ag-Ais are located at pins 24-31. 

■ A4/5, A6/7: Combined addresses from the microprocessors. Used along with 
simple addresses, combined in this fashion to lower the pin count of the 
MMU. Located at pins 22 and 23 respectively. 

■ PHIq: Presystem clock. Used for early transition of gated signals on write 
operations. Processor address is valid on the rising edge, and data is valid on 
the falling edge. This is found at pin 33. 

■ R/W: System Read/Write control line. This input is high for a processor read, 
low for a processor write. This signal is located at pin 32 on the MMU chip. 

■ RESET: System Reset. This input initializes internal registers on a power-up 
or hardware reset. It can be found at pin 2. 

■ AEC; Address Enable Control. Indicates whether the 8502 processor or the 
VIC has access to the shared bus. When low, VIC or an external DMA has the 
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' ' bus and VAjg have the processor bus, and no pointer or BIOS translation takes 

place. This signal occupies pin 16. 
r^ ■ MUX: The memory multiplex signal, used to clock various sections of the 

j I MMU. It is located at pin 17. 

■ Vdj: System +5 Vdc supply, connected at pin 1. 
r^ ■ Vss: System Ground, connected at pin 34. 

i ! 

The following represents the MMU bidirectional lines. Some of the port bits 
detailed here are left for future expansion in a one-directional sense. 

n 

! \ ■ D0-D7: Data inputs from microprocessor. Used for writing to internal regis- 

ters. Located at pins 35 to 42. 

■ /EXROM: This signal is used to sense the /EXROM line on the expansion 
connector in C64 mode and as an expansion control line in C128 mode. 
Located at pin 46. This line will drive one TTL load on ouq)ut, and has a 
passive depletion mode pull-up on input. This signal can be pulled down, but 
not up, by an external driver. 

■ /GAME: This signal is used to sense the /GAME line on the expansion 
connector in C64 mode and as the color RAM bank control line in C128 mode. 
Located at pin 45. This line will drive one TTL load on output, and has a 
passive depletion mode pull-up on input. External hardware can pull this line 
down, but not up. 

■ 40/80: This port in input mode senses the 40/80 column switch. It detects 
whether or not this switch is closed. Its output function is open for expansion. 
Located at pin 48. This line will drive one TTL load on ou^ut, and has a 
passive depletion mode pull-up on input. External hardware can pull tiiis line 
down, but not up. 

■ FSDIR: This port in output mode is used to control the data direction of the fast 
serial disk interface. It is a general-purpose port signal, and is connected at pin 
44. This line will drive one TTL load on output, and has a passive depletion 
mode pull-up on input. External hardware can pull this line down, but not up. 

The following list represents the MMU output signals, their physical locations on 
the MMU and their logical levels if applicable. 

■ TAg-TAis: Translated address outputs. Tri-stated for VIC cycles during AEC, 
they provide translated physical addresses for use on the Multiplexed Address 
Bus and the Shared Static Bus. TA12 to TA15 are each defined to have an 
internal, depletion mode pull-up with an equivalent resistance of 3.3Kfi. TAg 
to TAij each go tri-state during VIC time (AEC low). These are located on the 
MMU at pins 10 to 3. 

■ MSo-MSi: Also called ROMBANKO and ROMBANKl, these outputs control 
ROM banking for all ROM slots. They are located on pins 15 and 14. These 
lines are used to decode ROM bank selection for any ROM access in C128 
mode. If they are both low, a system ROM has been selected. If MSi alone is 



586 COMMODORE 128 



ABSOLUTE MAXIMUM RATINGS 



ITEM SYMBOL RANGE UNITS 



input Voltage Vu, -2.0 to +7.0 Vdc 

Supply Voltage V., -20 to +7.0 Vdc 

Operating Temperature T, 0to70 °C 

Storage Temperature T^ SS to 150 °C 

Table I&-I0. Absolute Maximum Ratings for the MMU 

MAXIMUM OPERATING CONDITIONS 



ITEM 






SYMBOL 


RANGE 


UNITS 


Voltage Variance 






v„ 


5.0 ± 5% 


Vdc 


Input Leakage Current 






II 


-1.0 


^A 


Input High Voltage 






ViH 


V»s + 2.4toVcc+1.0 


Vdc 


Input Low Voltage 






Vn. 


Vss-2.0toVs8 + 0.8 


Vdc 


Output High Voltage 






VoH 


\ss + 2A 


Vdc 


OOH = -200|XA. Vec = 


5V 


± 5%) 








Output Low Voltage 






Vol 


V«, + 0.4 


Vdc 


(loL = -3.2mA, Vcc = 


5V 


± 5%) 








Maximum Input Current 






I« 


250 


mA 



a 
u 



high, then a built-in function ROM has been selected. If MSo alone is high, 

then an external function ROM has been selected. Finally , if both are high, the 

RAM that occupies the particular slot has been selected. In C64 mode, the i j 

PLA completely ignores these lines. U 

I/O: This output is used to select memory mapped I/O in CI 28 mode. It is on 

pin 13, and is also known as MSj. In C128 mode, this line always reflects the ^ -^ 

polarity of the I/O bit. It is ignored by the PLA in C64 mode, and remains jj 

high throughout C64 mode. 

C128: This output directs the system to act in either C128 or C64 mode. It is 

located on pin 47, and is also known at MS3. It goes low to indicate C64 | I 

mode, high for C128 mode. J 

/Z80EN: This output is used to enable the Z80 processor and disable the 

normal operation of the 8502 processor. It can be found at pin 43. It goes low , - 

to indicate Z80 mode, high for all other modes. [J 

/CASa-CAS,: CAS enables to control RAM banking. CASq enables the first ^ 

bank of 64K; CASi enables the second bank of 64K. These are pins 12 and 

11, respectively. I 
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Table 16-1 1. Maximum Operating Conditions for the MMU L 
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Figure 16-9. The Memory Management Unit Pin Configuration 
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THE 8564 

VIDEO INTERFACE CHIP 



As these functions exist in the previous VIC, their description is purposely kept to 
a minimum here, while the VIC programming information is contained in Chapter 8. The 
new functions, however, are described in detail below. 

EXTENDED KEYBOARD SCANNING 

The 8564 contains a register called the Keyboard Control Register. This register 
allows scanning of three additional keyboard control lines on the CI 28 keyboard. Thus, 
the CI 28 keyboard can have advanced additional keys in CI 28 mode while still 
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The 8564 VIC chip used in the C128 is an updated version of the VIC chip used in 
current C64 systems. It contains all the video capabilities of the earlier 6567 VIC chip, 
including high-resolution bit-mapped graphics and movable image blocks. It also sup- 
ports new features used by the C128 system, including extended keyboard scanning. Its 
register map is upwardly compatible with the old VIC, allowing compatibility in C64 , 

mode. It is powered by a single, 5V DC source instead of the two sources required by j 

the old VIC chip. The 8564 pin configuration is shown in Figure 16-10. 

GENERAL DESCRIPTION IJ 

The 8564 VIC chip is similar to the 6567 VIC chip, yet it supports many new 

features unique to the C128 system requirements. It will run on a single 5V DC supply, \ i 

and is packaged in a 48-pin dual-in-line package. |J 

8564 VIC OPERATIONS 

The 8564 VIC supports all the operations of the previous VIC chip. These functions, ] j 

quickly summarized, are: 

■ Standard color character display mode. \ I 

■ Multicolor character display mode. \j 

■ Extended color character display mode. 

■ Standard bit map mode. . 

■ Multicolor bit map mode. j 

■ Movable image blocks. ^ 

■ Movable image block magnification. 

■ Movable image block priority j 

■ Movable image block collision detection u. 

■ Screen blanking 

■ Row/column display select i I 

■ Smooth scrolling \ I 

■ Light pen 

■ Raster compare interrupt 
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retaining C64 keyboard compatibility in C64 mode. In this register (register 53295 
($D02F)), bits 0-2 are directly reflected in output lines Kq to Kj, while bits 3-7 are 
unused, returning high when read. 

2 MHz OPERATION 

The VIC chip contains a register that allows the CI 28 system to operate at 2 MHz 
instead of the standard 1 MHz speed of the C64. This operating speed, however, 
disallows the use of the VIC chip as a display processor. This is bit in 53296 ($D030), 
and setting this bit enables 2 MHz mode. During 2 MHz operations, the VIC is disabled 
as a video processor. The processor spends the full tune cycle on the bus, while VIC is 
responsible only for dynamic RAM refresh. Clearing this bit will bring back 1 MHz 
operation and allow the use of the VIC as a video display chip. During refresh and I/O 
access, the system clock is forced to 1 MHz regardless of the setting of this bit. 

The 2MHz speed is available in C64 mode by setting bit of location 53296 
($D030). Prior to this, blank the screen by clearing bit 4 of location 53265 ($D011). 
You can then process at 2MHz (to perform number crunching, for example); however, 
you will have no visible VIC screen. To return, set bit 4 of 53265 ($D011) and clear bit 
of 53296 ($D030). 

Bit 1 of this register contains a chip-testing facility. For normal operation, this bit 
must be clear. None of the other bits in this register is connected. 

SYSTEM CLOCK CONTROL 

The new VIC chip generates several clocks used by the C128 system. The main clock is 
the 1 MHz clock, which operates at approximately 1 MHz at all times. Most bus 
operations and all I/O operations take place in reference to this clock. The next clock to 
consider is the 2 MHz clock. This clock clocks selected system components, such as the 
processor, at 2 MHz when in 2 MHz mode. The VIC chip monitors the /lOACC input, 
which indicates the access of an 1/0 chip, and when asserted, will stretch the 2 MHz 
clock to synchronize all 2 MHz parts with the 1 MHz I/O parts. Finally, the last clock is 
the Z80 clock, which is a 4 MHz clock that takes place only during the low half of the I 
MHz clock. Since all timed I/O parts look only at the 1 MHz clock, all I/O timings 
remain the same no matter what the 2 MHz clock is doing. 

SIGNAL DESCRIPTION 

The VIC chip is mounted in a 48-pin dual-in-line package. The following lists describe 
the electrical signals that it generates. 

The signals used in the system interface are: 

■ Dfl-Dy: These are the bidirectional data bus signals. They are for communica- 
tion between the VIC and the processor, and can be accessed only during AEC 
high. They occupy pins 7 through 1 and 47, respectively. 

■ Dg-Dii: These are the extended data bus signals. They are used for VIC 
communication with the color RAM. They occupy pins 47 to 43 in order. 

■ /CS: Chip select, used by the processor to select the VIC chip. Found at pin 13. 

■ R/W: Standard 8502 bus read/write for interface between the processor and 
the various VIC registers. Pin 14. 
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ELECTRICAL SPECIFICATION 

Tables 16-12 and 16-13 specify the electrical operation of the VIC chip in its new form. 
These specs include absolute maximum ratings and maximum operating conditions. 



■ A(r-A«: Multiplexed address lines, pins 32 through 38. During row address L 
time, Ao-Ag are driven on A0-A5. During column address time, Ag-An are 

driven on Ao- A5 and Ag is held at 1 . During a processor read or write, A0-A5 i / 

serve as address inputs that latch on the low edge or /RAS. jj 

■ A-A]o: Static address lines, pins 39 through 42. These address lines are used 

for non-multiplexed VIC memory accesses, such as to character ROM and ^ 

color RAM. j ! 

■ IMHz: The 1 MHz system clock, pin 18. All system bus activity is referenced '-' 
to this clock. 

■ 2MHz: This is the changing system clock, which will be either 1 MHz or 2 | ( 
MHz. If the 2 MHz bit is clear, no VIC or external DMA is taking place, and IJ 
no I/O operation is occurring, the clock wiU be 2 MHz; otherwise it will be 1 

MHz. Found at pin 23. \ 1 

■ Z80 Phi: The special 4 MHz Z80 clock, pin 25. U 

■ /lOACC: From PLA, indicating an I/O chip access for clock stretching. Pin 22 
of the VIC. 

■ /RAS: Row address strobe for DRAMs, pin 19. | j 

■ /CAS: Column address strobe for DRAMs, pin 20. U 

■ MUX: Address multiplexing control for DRAMs, pin 21. 

■ /IRQ: Interrupt output, used to signal one of the various internal interrupt i ; 
sources has taken place. Requires a pull-up, found at pin 8 on the chip. [J 

■ AEC: Address Enable Control, high for processor enable on the shared bus, 

low for VIC cycle and VIC or external DMA. Found at pin 12 of the VIC. ^ 

■ BA: Bus Available signal, used to DMA processor. Pin 10. j 

■ K0-K2: Extended keyboard strobe bits, pins 26 to 28. •— ^ 

■ LP: Edge triggered latch for light pen input. Pin 9 of the VIC chip. 

The signals comprised in the video interface, i.e., all the signals required to create JJ 

a color video image, are: 

■ PH IN: The fundamental shift rate clock, also called the dot clock. Used as the il 
reference for all system clocks. Located at pin 30. 

■ PH CL: The color clock, used to derive the chroma signal. Pin 29. 

■ SYNC: Output containing composite sync information, video data and lumi- | 
nance information. Requires a pull-up, pin 17. U 

■ COLOR: Output containing all color-based video information. Open source 

output, should be tied through a resistor to ground. Found at pin 16. i / 
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/ I 



ITEM 



SYMBOL RANGE 



UNIT 



Input Voltage Vi„ 

Supply Voltage Vcc 

Operating Temperature T, 

Storage Temperature T„ 



-0.5 to +7.0 Vdc 

-0.5 to +7.0 Vdc 

to 75 °C 

-65 to 150 °C 



Table 16-12. Absolute Maximum Ratings for VIC Chip 
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Below is a list of the maximum operating specifications for the new VIC chip: 



n 

n 

i I 



ITEM 






SYMBOL 


RANGE 


UNTT 


Power Supply Variance 






Ycc 


5.0 ± 5% 


Vdc 


Input Leakage Current 






II 


-1.0 


ftA 


Input High Voltage 






Vm 


V» + 2.0toVcc 


Vdc 


Input Low Voltage 






Vn. 


V«r0.5toV«, + 0.8 


Vdc 


Output High Voltage 






VOH 


V„+2.4 


Vdc 


aoH=-200fiA, V„ = 5.0 ± 


5% 


Vdc) 








Output Low Voltage 






Vol 


Vss+0.4 


Vdc 


(IoL= -3.2mA, Vcc =5.0 ± 


5% Vdc) 








Max Power Supply Current 






Ice 


200 


mA 



Table 16-13. Maximum Operating Specifications for VIC Chip 



RASTER REGISTER 

The Raster Register is a dual function register. A read of the raster register 53266 ($D012) 
returns the lower 8 bits of the current raster position [the MSB-RC8 ts located in register 
53265 ($D01 1)]. A write to the raster bits (including RC8) is latched for use in an internal 
raster compare. When the current raster matches the written value, the raster interrupt 
latch is set. The raster register should be interrogated to prevent display flicker by 
delaying display changes to occur outside the visible area. The visible area of the 
display is from raster 51 to raster 251 ($033-$OFB). 



INTERRUPT REGISTER 

The Interrupt Register indicates the status of the four sources of interrupts. An interrupt 
latch in register 53273 ($D019) is set to 1 when an interrupt source has generated an 
interrupt request. 
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LATCH ENABLE 

BIT BIT 

mST ERST 

IMDC EMDC 

n^lMC EMMC 

ILP ELP 
IRQ 



WHEN SET 

Actual raster count = stored raster count (bit 0) 
MOB-DATA coUision (first bit only) (bit 1) 
MOB-MOB collision (first bit only) (bit 2) 
First negative transition of LP per frame (bit 3) 
When IRQ/ output low (bit 7) 



Table 16-14. Interrupt Register Definitions 



To enable an interrupt request to set the IRQ/ output to 0, the corresponding interrupt 
enable bit in register 53274 ($D01A) must be set to "1". Once an interrupt latch has 
been set, the latch may be cleared only by writing a "1" to the associated bit in the 
interrupt register. This feature allows selective handling of video interrupts without 
software storing the active interrupts. 

SCREEN BLANKING 

The display screen can be blanked by clearing the BLNK bit (bit 4) in register 53265 
($D01I) to zero (0). When the screen is blanked, the entire screen displays the exterior 
color specified by register 53280 ($D020). When blanking is enabled, only transparent 
(phase 1) memory accesses are requu-ed, permitting full processor utilization of the 
system bus. However, sprite data will be accessed if the sprites are not also disabled. 



u 

u 
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DISPLAY ROW/COLUMN SELECT 

The normal display screen consists of 25 rows of 40 character regions per row. For 
special display purposes, the display window is reduced to 24 rows of 38 characters. 
There is no change in the format of the display information, except that characters (bits) 
adjacent to the exterior border area are covered by the border. 
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RSEL NUMBER OF ROWS CSEL NUMBER OF COLUMNS 

24 rows 38 columns 

1 25 rows 1 40 columns 



The RSEL bit (bit 3) is in register 53265 ($D011), and the CSEL bit (bit 3) is in 
register 53270 ($D016). For standard display, the larger display window is normally 
used, while the smaller display window is normally used in conjunction with scrolling. 

SCROLLING 

The display data may be scrolled up to one character in both the horizontal and vertical 
du-ections. When used in conjunction with the smaller display wmdow (above), scrolling 
can be used to create a smooth panning motion of display data while updating the 
system memory only when a new character row (or column) is required. Scrolling is 
also used for centering a display within the border. An example of horizontal smooth 
scrolling is found in Chapter 8. 



BITS REGISTER FUNCTION 

0-2 53270 ($D016) Horizontal Position 

0-2 53265 ($D011) Vertical Position 



LIGHT PEN 

The light pen input latches the current screen position into a pair of registers (LPX, 
LPY) on a low-going edge. Since the X position is defined by a 9-bit counter (53267 
($D013)), resolution to 2 horizontal dots is provided. Similarly, the Y position is latched 
in register 53268 ($D014) with 8 bits providing unique raster resolution within the 
visible display. The light pen latch may be triggered only once per frame, and subse- 
quent triggers within the same frame will have no effect. 

For more information on programming the VIC (8564) chip, see Chapter 8, The 
Power Behind Commodore 128 Graphics. 
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Figure 16-10. The 8564 VIC Chip 
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THE 8563 

n VIDEO CONTROLLER 

I i ■ — ■ 

The 8563 is a HMOSII technology custom 80-column, color video display controller. 
ii The 8563 supplies all necessary signals to interface directly to 16K of DRAM, including 

' ' refresh, and generated RGBI for use with an external RGBI monitor. For more informa- 

tion on the 8563 video controller, see Chapter 10, Progranuning the SO-Column (8563) Chip. 

GENERAL DESCRIPTION 

The 8563 is a text display chip designed to implement an 80-column display system with 
{| a minimum of parts and cost. The chip contains the high-speed pixel frequency logic 

/ 1 necessary for 80-column RGBI video. It can drive loads directly, though some buffering 

is desirable in most real- world applications. The chip can address up to 64K of DRAM 
|-n for character font, character pointer, and attribute information. The chip provides RAS, 

! j CAS, write enable, address, data and refresh for its subordinate DRAMs. A program- 

mable bit selects either two 4416 DRAMs (16K total) or eight 4164 DRAMs (64K total) 
for the display RAM. The C128 system uses the 4416 DRAMs. 



n 



EXTERNAL REGISTERS 

The 8563, which sits at $D600 in the CI 28, appears to the user as a device consisting of 
only two registers. These two registers are indirect registers that must be programmed to 
access the internal set of thuty-seven programming registers. The first register, located 
at $D600, is called the Address Register. Bit 7 of $D600 is the Update Ready Status Bit. 
When written to, the five least significant bits convey the address of an internal register 
to access in some way. On a read of this register, a status byte is returned. Bit 7 of this 
register is low while display memory is being updated, and goes high when ready for the 
next operation. The sixth bit will return low for an invalid light pen register condition and 
high for a valid light pen address. The final register indicates with a low that the scan is 
not in vertical blanking, and with a high that it is in vertical blanking. 

The other register is the Data Register. It can be read from and written to. Its 
purpose is to write data to the internal register selected by the address register. All 
internal registers can be read from and written to through this register, though not all of 
them are a full 8 bits wide. 

INTERNAL REGISTERS 

There are thirty-seven internal registers in the 8563, used for a variety of operations. 
They fall into two basic groups: setup registers and display registers. Setup registers are 
used to define internal counts for proper video display. By varying these registers, the 
user can configure the 8563 for NTSC, PAL or other video standards. 

The display registers are used to define and manipulate characters on the screen. 
Once a character set has been downloaded to this chip, it is possible to display 
80-column text in 4-bit digital color. There are also block movement conmiands that 
remove the time overhead needed to load large amounts of data to the chip through the 
two levels of indirection. Figure 16-11 is a display of the 8563 internal register map. 
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Figure 16-11. 8563 Register Map 



SIGNAL DESCRIPTION 

There are many different signals involved with the 8563 chip, but they can be divided 
into three general categories. The CPU interface signals serve as an interface to the 8502 
bus. The local bus management signals serve to maintain the local memory bus. Finally, 
the video interface signals are the signals that are necessary to provide an RGBI image 
on an RGBI monitor. The 8563 pin configuration is shown in Figure 16-12. 

THE CPU INTERFACE 

The 8563 chip interfaces to the 8502 bus using a minimum of signals. This is due 
mainly to the local memory used by the 8563. The CPU interface signals are as follows: 

■ Dcr-D?: Bidirectional data bus allowing data to be passed between the 8563 
and 8502. Found on pins 18 to 13, 11 and 10. 

■ OS: Chip select input. This input must be high for selection and proper 
operation of the chip. Located at pin 4. 

■ /CS: Chip select input. This input must be low for selection and proper 
operation of the chip. Located at pin 7. 
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■ /RS: Register Select input. A high allows reads and writes to the selected data 
register. A low allows reads of the status register and writes to the address 
register. In the system, this line is tied to AO. It is located at pin 8. 

■ RAV: This line controls the data direction for the data bus. This is a typical 
8502 control signal. Found at pin 9. 

■ INIT: Active low input for clearing internal control latches, allowing the chip 
to begin operation following initial power-on. Connect to /RES in the C128, 
at pin 23. 

■ DISPEN: Display Enable output signal, unused in the C128. Found at pin 19. 

■ RES: This input initializes all internal scan counters, but not control registers. 
It is not actively used in the CI 28 circuit, and is not found at pin 22. 

■ TST: Pin used for testing only, tied to ground in the C128. Located at pin 24 
of the chip. 

THE LOCAL BUS MANAGEMENT INTERFACE 

The local bus management interface is a group of signals generated by the 8563 for the 
management of local video DRAM. This local DRAM both simplifies the addition of an 
80-column video display to a system and enables a computer system with a limited 
address space to support an 80-column display without taxing its limited memory 

]i resources. 

i I 

■ DDtrODf. Bidkectional local display DRAM data bus, comprising pins 35-36 
n and 38-42. 

I \ ■ DA0-DA7: Local display DRAM multiplexed address bus. Takes up pins 

26-33. 
p, ■ DRAV: Local display DRAM ReadAVrite, pin 21. 

I i ■ /RAS: Row Address Strobe for local DRAM, pin 47. 

' ' ■ /CAS: Column Address Strobe for local DRAM, pin 48. 

P THE VIDEO INTERFACE 

I i The final set of 8563 signals are the video interface signals. These signals are directly 

related to the display video image. 
«i 
^1 ■ DCLK: Video Dot Clock, determines the pixel width and is used internally as 

the timing basis for all synchronized signals, such as character clock and 

DRAM timing. Found at pin 2. 
( I ■ CCLK: The character clock output, unused in the C128 system, and found at pin 1 . 

I i ■ LP2: Input for light pen; a positive going transition on this input latches the 

vertical and horizontal position of the character being displayed at that time. 
'^ Found at pin 25. 

I I ■ HSYNC: The horizontal sync signal, fully programmable via internal 8563 

registers, and found at pin 20. 
-. ■ R,G,BJ: The pixel data outputs. They form a 4-bit code associated with each 

I pixel, containing color/intensity information, allowing a total of sixteen colors 

' or gray shades to be displayed. Located at pins 46, 45, 44, 43, respectively. 
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Figure 16-12. The 8563 Chip Pin Configuration 
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6581 SOUND rNTERFACE DEVICE (SID) 
CHIP SPECIFICATIONS 

CONCEPT 

The 6581 Sound Interface Device (SID) is a single-chip, three-voice electronic music 
synthesizer/sound effects generator compatible with the 8502 and similar microprocessor 
families. SID provides wide-range, high-resolution control of pitch (frequency), tone 
color (harmonic content), and dynamics (volume). Specialized control circuitry mini- 
mizes software overhead, facilitating use in arcade/home video games and low-cost 
musical instruments. 

FEATURES 

■ 3 TONE OSCILLATORS 
Range: CM kHz 

■ 4 WAVEFORMS PER OSCILLATOR 
n Triangle, Sawtooth, 

Variable Pulse, Noise 

■ 3 AMPLITUDE MODULATORS 
Range: 48 dB 

■ 3 ENVELOPE GENERATORS 
Exponential response 
Attack Rate: 2ms-8 s 
Decay Rate: 6 ms-24 s 
Sustain Level: 0-peak volume 
Release Rate: 6 ms-24 s 

p ■ OSCILLATOR SYNCHRONIZATION 

■ RING MODULATION 

■ PROGRAMMABLE FILTER 
Cutoff range: 30 Hz-12 kHz 
12 dB/octave Rolloff 
Low pass. Bandpass, 
High pass. Notch outputs 
Variable Resonance 

■ MASTER VOLUME CONTROL 

■ 2 A/D POT INTERFACES 

■ RANDOM NUMBER/MODULATION GENERATOR 

■ EXTERNAL AUDIO INPUT 



n 



n 



600 COMMODORE 128 







^^ 




CAPiA 


1 




28 








— ' 


CAPiB 


2 




27 








IZZ 


CAP2A 


3 




26 








^7 


CAP2B 


4 




25 








^^^ 


RES 


5 




24 








= 


«2 


6 




23 


R/W 


7 


6581 
SID 


22 


CS 


8 




21 


Ao 


9 




20 


Ai 


10 




19 


A2 


11 




18 


A3 


12 




17 








ZT 


A4 


13 




16 








— 


GNO 


14 




15 











Vdd 
audio out 

EXT IN 

Vcc 

POTX 

POTY 

D7 

De 
D5 
D4 
D3 
D2 

O1 

Do 



Figure 16-13. 6581 SID Pin Configuration 
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Figure 16-14. 6581 Block Diagram 
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DESCRIPTION 

The 6581 consists of three synthesizer "voices" which can be used independently or in 
conjunction with each other (or external audio sources) to create complex sounds. Each 
voice consists of a Tone Oscillator/Waveform Generator, an Envelope Generator and an 
Amplitude Modulator. The Tone Oscillator controls the pitch of the voice over a wide 
range. The Oscillator produces four waveforms at the selected frequency, with the 
unique harmonic content of each waveform providing simple control of tone color. The 
volume dynamics of the oscillator are controlled by the Amplitude Modulator under the 
direction of the Envelope Generator. When triggered, the Envelope Generator creates an 
amplitude envelope with programmable rates of increasing and decreasing volume. In 
addition to the three voices, a programmable Filter is provided for generating complex, 
dynamic tone colors via subtractive synthesis. 

SID allows the microprocessor to read the changing output of the third Oscillator 
and third Envelope Generator. These outputs can be used as a source of modulation 
information for creating vibrato, frequency/filter sweeps and similar effects. The third 
oscillator can also act as a random number generator for games. Two A/D converters are 
provided for interfacing SID with potentiometers. These can be used for "paddles" in a 
game environment or as front panel controls in a music synthesizer. SID can process 
external audio signals, allowing multiple SID chips to be daisy-chained or mixed in 
complex polyphonic systems. For full register descriptions, see Chapter 11, Sound and 
Music on the Commodore 128. 

SID PIN DESCRIPTION 

CAP I A, CAP IB, (PINS 1,2)/ CAP2A,CAP2B (PINS 3,4) 

These pins are used to connect the two integrating capacitors required by the program- 
mable filter. CI connects between pins 1 and 2, C2 between pins 3 and 4. Both 
capacitors should be the same value. Normal operation of the filter over the audio range 
(approximately 30 Hz-12 kHz) is accomplished with a value of 2200 pF for CI and C2. 
Polystyrene capacitors are preferred and in complex polyphonic systems, where many 
SID chips must track each other, matched capacitors are recommended. 

The frequency range of the filter can be tailored to specific applications by the 
choice of capacitor values. For example, a low-cost game may not require full high- 
frequency response. In this case, large values for CI and C2 could be chosen to provide 
more control over the bass frequencies of the filter. The maximum cutoff frequency of 
the filter is given by: 

FC^ax = 2.6E-5/C 

where C is the capacitor value. The range of the filter extends nine octaves below the 
maximum cutoff frequency. 

RES (PIN 5) 

This TTL-level input is the reset control for SID. When brought low for at least ten <|)2 
cycles, all internal registers are reset to and the audio output is silenced. This pin is 
normally connected to the reset line of the microprocessor or a power-on-clear circuit. 
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<t>2 (PIN 6) 

This TTL-level input is the master clock for SID. All oscillator frequencies and 
envelope rates are referenced to this clock. <|)2 also controls data transfers between SID 
and the microprocessor. Data can only be transferred when <|)2 is high. Essentially, <|)2 acts 
as a high-active chip select as far as data transfers are concerned. This pin is normally 
connected to the system clock, with a nominal operating frequency of 1.0 MHz. 

R/W (PIN 7) 

This TTL-level input controls the direction of data transfers between SID and the 
microprocessor. If the chip select conditions have been met, a high on this line allows 
the microprocessor to Read data from the selected SID register and a low allows the 
microprocessor to -Write data into the selected SID register. This pin is normally 
connected to the system Read/Write line. 

CS (PIN 8) 

This TTL-level input is a low active chip select which controls data transfers between 
SID and the microprocessor. CS must be low for any transfer. A Read from the selected 
SID register can only occur if CS is low, ^1 is high and R/W is high. A Write to the 
selected SID register can only occur if CS is low, <|)2 is high and R/W is low. This pin is 
normally connected to address decoding circuitry, allowing SID to reside in the memory 
map of a system. 



A0-A4 (PINS 9-13) 

These TTL-level inputs are used to select one of the 29 SID registers. Although enough 

_. addresses are provided to select one of thirty-two registers, the remaining three register 

I locations are not used. A Write to any of these three locations is ignored and a Read 

returns invalid data. These pins are normally connected to the corresponding address 

lines of the microprocessor so that SID may be addressed in the same manner as 

I I memory. 

I I 

GND(PIN 14) 

rj For best results, the ground line between SID and the power supply should be separate 

' ' from ground lines to other digital circuitry. This will minimize digital noise at the audio 

output. 

I Da<D7 (PINS 15-22) 

These bidirectional lines are used to transfer data between SID and the microprocessor. 
"1 They are TTL compatible in the input mode and capable of driving two TTL loads in the 

I output mode. The data buffers are usually in the high-impedance off state. During a 

Write operation, the data buffers remain in the off (input) state and the microprocessor 
supplies data to SID over these lines. During a Read operation, the data buffers tum on 
and SID supplies data to the microprocessor over these lines. The pins are normally 
connected to the corresponding data lines of the microprocessor. 
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POTX,POTY (PINS 24,23) 

These pins are inputs to the A/D converters used to digitize the position of potentiome- 
ters. The conversion process is based on the time constant of a capacitor tied from the j 

POT pin to ground, charged by a potentiometer tied from the POT pin to + 5 volts. The '-' 

component values are determined by: 

RC = 4JBrA L 

Where R is the maximum resistance of the pot and C is the capacitor. 

The larger the capacitor, the smaller the POT value jitter. The recommended 
values of R and C are 470 kft and 1000 pF. Note that a separate pot and cap are required '-' 

for each POT pin. 



Vcc (PIN 25) 

As with the GND line, a separate +5 VDC line should be run between SID Vcc and the 
power supply in order to minimize noise. A bypass capacitor should be located close to 
the pin. 



u 



EXT IN (PIN 26) 

This analog input allows external audio signals to be mixed with the audio output of SID 

or processed through the Filter. Typical sources include voice, guitar, and organ. The 

input impedance of this pin is on the order of 100 kfl. Any signal applied directly to the 

pin should ride at a DC level of 6 volts and should not exceed 3 volts p-p. In order to 

prevent any interference caused by DC level differences, external signals should be 

AC-coupled to EXT IN by an electrolytic capacitor in the 1-10 \if range. As the direct 

audio path (FILTEX = 0) has unity gain, EXT IN can be used to mix outputs of many j I 

SID chips by daisy-chaining. The number of chips that can be chained in this manner is ^ 

determined by the amount of noise and distortion allowable at the fmal output. Note that 

the output volume control will affect not only the three SID voices, but also any external i 

inputs. L 

AUDIO OUT (PIN 27) I | 

This open-source buffer is the fmal audio output of SID, comprised of the three IJ 

SID voices, the filter and any external input. The output level is set by the output 
volume control and reaches a maximum of 2 volts p-p at a DC level of 6 volts. A 
som-ce resistor from Audio Out to ground is required for proper operation. The recom- 
mended resistance is 1 kft for a standard output impedance. 

As the output of SID rides at a 6-volt DC level, it should be AC-coupled to any 
audio amplifier with an electrolytic capacitor in the 1-10 ftf range. 

Vdd (PIN 28) 

As with Vcc, a separate + 12 VDC line should be run to SID Vdd and a bypass capacitor i 

should be used. L 



u 
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6581 SID CHARACTERISTICS 



ABSOLUTE MAXIMUM RATINGS 



n 

n 

I! 

n 



RATING 

Supply Voltage 
Supply Voltage 
Input Voltage (analog) 
Input Voltage (digital) 
Operating Temperature 
Storage Temperature 



SYMBOL VALUE 



UOTTS 



Vdd -0.3 to +17 VDC 

Vcc -0.3 to +7 VDC 

Vtea -0.3 to +17 VDC 

Vi„d -0.3 to +7 VDC 

Ta to +70 "C 

TsTG -55 to +150 "C 



ELECTRICAL CHARACTERISTICS 

(Vdd = 12 VDC ±5%, Vcc = 5 VDC ±5%, Ta = to 70° C) 



CHARACTERISTIC 



SYMBOL MIN TYP MAX 



UNITS 



n 



Input High Voltage 
Input Low Voltage 


(RES, (|)2, WW, CS 
A0-A4, D0-D7) 




2 
-0.3 


Input Leakage Current 
Three-State (Off) 


(RES, <|)2, RAV, CS, 
A0-A4; Vta = 0-SVDC) 
(D0-D7; V„ = max) 


lin 

Itsi 


^■' 


Input Leakage Current 


Vta = 0.4-2.4 VDC 






Output High Voltage 


(D0-D7; Vcc = min, 
1 load = 200^ A) 


VoH 


2.4 


Output Low Voltage 


(D0-D7; Vcc = max, 
1 load = 3.2 mA) 


Vol 


GOT 


Output High Current 


(D0-D7; Sourcing, 
VoH=2.4VDC) 


loH 


200 


Output Low Current 


(D0-D7; Sinking 
Vol = 0.4 VDC) 


Id 


3.2 


Input Capacitance 


(RES, <t)2, RAV, CS, 
A0-A4, D0-D7) 


c,„ 


— 


Pot Trigger Voltage 


(POTX, POTY) 


Vp., 


— 


Pot Sink Current 


(POTX, POTY) 


Ipo. 


500 



- Vcc/2 



V.C 


VDC 


0.8 


VDC 


2.5 


fxA 


10 


|xA 


V„-0.7 


VDC 


0.4 


VDC 


— 


M.A 


— 


mA 


10 


pF 


— 


VDC 


— 


P.X 
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CHARACTERISTIC 



SYMBOL MIN TYP MAX 



Input Impedance 
Audio Input Voltage 

Audio Output Voltage 



Power Supply Current 
Power Supply Current 
Power Dissipation 



(EXT IN) R„ 

(EXT IN) Vi„ 

(AUDIO OUT; 1 lift 

load, volume = max) Vout 
One Voice on: 
All Voices on: 

(Vdo) Idd 

(Vec) Ice 

(Total) Pd 



100 



5.7 
0.4 
1.0 



150 — 



5.7 6 
— 0.5 



6 

0.5 

1.5 



— 20 

— 70 

— 600 



6.3 
3 

6.3 
0.6 
2.0 

25 

100 

1000 



u 



UNITS 

kft 

VDC 
VAC 



VDC 
VAC 
VAC 

mA 

mA 

mW 



u 



6581 SID TIMING 



Tr- 



f 



nnl 



f 



A0-A4 



IZfflSC 



cs 



ASSSi. 



D0-07 ■ 



■^ 



\ 



*^ACC 'S measured from the latest occurring ol o?. CS. Ag-Aa. 



MIN TYP MAX 



SYMBOL 


NAME 


MIN 


TcYC 


Clock Cycle Time 


1 


Tc 


Clock High Pulse Width 


450 


Tr,Tf 


Clock Rise/Fall Time 


— 


Trs 


Read Set-Up Time 





Trh 


Read Hold tune 





Tacc 


Access Time 


— 


Tah 


Address Hold Time 


10 


TcH 


Chip Select Hold Time 





Tdh 


Data Hold Time 


20 



500 



20 (IS 

10,000 ns 

25 ns 

— ns 

— ns 
300 ns 

— ns 
-^ ns 

— ns 



Figure 16-15. Read Cycle 



u 



^ 



3C 



r~ 



UNITS 



>- 



u 



u 



u 



n 

n 



n 
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f 



wwww 



-Tw" 



-TwH 



IXXM 



■\sxxxi 



Tah 

5C 

TCH 



h^v°-l|- 



D„.D, 



X 



n 



■Tyi, Is measured from the latest occurring o( oj. CS, R/W 



SYMBOL 


NAME 


MIN 


TYP 


MAX 


UNITS 


Tw 


Write Pulse Width 


300 


^_ 


^_ 


ns 


TwH 


Write Hold Time 











ns 


Taws 


Address Set-up Time 











ns 


Tah 


Address Hold Time 


10 





^ 


ns 


TcH 


Ciiip Select Hold Time 





— 


— 


ns 


TvD 


Valid Data 


80 








ns 


Tdh 


Data Hold Time 


10 


— 


— 


ns 



Figure 16-16. Write Cycle 

EQUAL-TEMPERED 
MUSICAL SCALE VALUES 



The table in Chapter 11 lists the numerical values which must be stored in the SID 
Oscillator frequency control registers to produce the notes of the equal-tempered musical 
scale. The equal-tempered scale consists of an octave containing twelve semitones 
(notes): C,D,E,F,G,A,B and C#,D#,F#,G#,A#. The frequency of each semitone is 
exactly the 12th root of 2 i^fl) times the frequency of the previous semitone. The table 
is based on a 4)2 clock of 1.02 MHz. Refer to the equation given in the Register 
Description in Chapter 11 for use of other master clock frequencies. The scale selected 
is concert pitch, in which A-4 = 440 Hz. Transpositions of this scale and scales other 
than the equal-tempered scale are also possible. 

Although the table in Chapter 11 provides a simple and quick method for generat- 
ing the equal-tempered scale, it is very memory inefficient as it requires 192 bytes for 
the table alone. Memory efficiency can be improved by determining the note value 
algorithmically. Using the fact that each note in an octave is exactly half the 
frequency of that note in the next octave, the note look-up table can be reduced from 
ninety-six entries to twelve entries, as there are twelve notes per octave. If the twelve 
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entries (24 bytes) consist of the 16-bit values for the eighth octave (C-7 through B-7), 
then notes in lower octaves can be derived by choosing the appropriate note in the eighth 
octave and dividing the 16-bit value by two for each octave of difference. As division by 
two is nothing more than a right-shift of the value, the calculation can easily be 
accomplished by a simple software routine. Although note B-7 is beyond the range of 
the oscillators, this value should still be included in the table for calculation purposes 
(the MSB of B-7 would requite a special software case, such as generating this bit in the 
CARRY before shifting). Each note must be specified in a form which indicates which 
of the twelve semitones is desired, and which of the eight octaves the semitone is in. 
Since 4 bits are necessary to select one of twelve semitones and 3 bits are necessary to 
select one of eight octaves, the information can fit in one byte, with the lower nybble 
selecting the semitone (by addressing the look-up table) and the upper nybble being used 
by the division routine to determine how many times the table value must be right-shifted. 



u 
U 




SID ENVELOPE GENERATORS 



The four-part ADSR (ATTACK, DECAY, SUSTAIN, RELEASE) envelope generator 
has been proven in electronic music to provide the optimum trade-off between flexibility 
and ease of amplitude control. Appropriate selection of envelope parameters allows the 
simulation of a wide range of percussion and sustained instruments. The violin is a good 
example of a sustained instrument. The violinist controls the volume by bowing the 
instrument. Typically, the volume builds slowly, reaches a peak, then drops to an 
intermediate level. The violinist can maintain this level for as long as desired, 
then the volume is allowed to slowly die away. A "snapshot" of this envelope is 
shown below: 



PEAK AMPLITUDE 



S 

-SUSTAIN - 
PERIOD 



ZERO AMPLITUDE 




u 
u 

1 
u 



Figure 16-17. ADSR Envelope 



u 



This volume envelope can be easily reproduced by the ADSR as shown below, 
with typical envelope rates: 



u 



n 
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ATTACK; 

DECAY 

SUSTAIN: 

RELEASE: 



10 ($A) 

8 
10 ($A) 

9 



500 ms 
300 ms 

750 ms 




OATE I 



Note that the tone can be held at the intermediate SUSTAIN level for as long as 
desired. The tone will not begin to die away until GATE is cleared. With minor 
alterations, this basic envelope can be used for brass and woodwinds as well as strings. 

An entirely different form of envelope is produced by percussion instruments such 
as drums, cymbals and gongs, as well as certain keyboards such as pianos and 
harpsichords. The percussion envelope is characterized by a nearly instantaneous attack, 
inmiediately followed by a decay to zero volume. Percussion instruments cannot be 
sustained at a constant amplitude. For example, the instant a drum is struck, the sound 
reaches full volume and decays rapidly regardless of how it was struck. A typical 
cymbal envelope is shown below: 



n 



ATTACK: 





2 ms 


DECAY: 


9 


750 ms 


SUSTAIN: 
RELEASE: 



9 


750 ms 



Note that the tone immediately begins to decay to zero amplitude after the peak is 
reached, regardless of when GATE is cleared. The amplitude envelope of pianos and 
harpsichords is somewhat more complicated, but can be generated quite easily with the 
ADSR. These instruments reach full volume when a key is first struck. The amplitude 
inmiediately begins to die away slowly as long as the key remains depressed. If the key 
is released before the sound has fully died away, the amplitude will inmiediately drop to 
zero. This envelope is shown below: 



ATTACK: 





2 ms 


DECAY: 


9 


750 ms 


SUSTAIN: 







RELEASE: 





6 ms 



Note that the tone decays slowly until GATE is cleared, at which point the 
amplitude drops rapidly to zero. 

The most simple envelope is that of the organ. When a key is pressed, the tone 
immediately reaches full volume and remains there. When the key is released, the tone 
drops immediately to zero volume. This envelope is shown below: 
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ATTACK 

DECAY 

SUSTAIN 

RELEASE: 



2iiis 

6 ms 

15 ($F) 

6ins 



GATE 



L 



u 



The real power of SID lies in the ability to create original sounds rather than 
simulations of acoustic instruments. The ADSR is capable of creating envelopes which 
do not correspond to any "real" instruments. A good example would be the "back- 
wards" envelope. This envelope is characterized by a slow attack and rapid decay 
which sounds very much like an instrument that has been recorded on tape then played 
backwards. This envelope is shown below: 



u 



u 



ATTACK: 

DECAY: 

SUSTAIN: 

RELEASE: 



10 ($A) 


15 ($F) 

3 



500 ms 
6ins 

72 ms 



GATE 



Many unique sounds can be created by applying the amplitude envelope of one 
instrument to the harmonic structure of another. This produces sounds similar to familiar 
acoustic instruments, yet notably different. In general, sound is quite subjective and 
experimentation with various envelope rates and harmonic contents will be necessary in 
order to achieve the desired sound. 



n 



CLOCK 
CIRCUIT 



RESET 
CIRCUIT 



Vcc 



■ .jIN 

BES 

-.; OUT 

R/W 



6S0X 
MPU 






2200 pF 
POUYSTHENE 



2200 pF 
P0LYSTVH6NE 



r 



ADDRESS DECODING 
OR ADDRESS LINE 



LA 



U 

D 

y 



Vcc 

AUDIO OUT 



CAP.B 
CAP,. 



CAPjB 



AUDIO 
ELECTROLYTIC '^^^ 



^) 



ELECTROLYTIC 



^) 



' 1 T^ 

^lOOOpF [ 

^ PAnr 



^T 
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Figure 16^18. Typical 6581/SID Application 
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6526 COMPLEX INTERFACE ADAPTER 
(CIA) CHIP SPECIFICATIONS 

DESCRIPTION 

The 6526 Complex Interface Adapter (CIA) is an 8502 bus compatible peripheral 
interface device with extremely flexible timing and I/O capabilities. Figure 16-19 shows 
the 6526 pin configuration. Figure 16-20 shows the 6526 block diagram. 

FEATURES 



I ! 



■ 16 Individually programmable I/O lines 

■ 8 or 16-bit handshaking on read or write 

■ 2 independent, linkable 16-bit interval timers 

n ■ 24-hour (AM/PM) time of day clock with programmable alarm 

I ( ■ 8-bit shift register for serial I/O 

■ 2TTL load capability 

■ CMOS compatible I/O lines 

■ 1 or 2 MHz operation available 

ORDERING INFORMATION 

MXS 6526 — 



n 



■ FREQUENCY RANGE 
NO SUFFIX =lMHz 
A = 2MHz 

PACKAGE DESIGNATOR 



n C = CERAMIC 

i I P = PLASTIC 



I i 
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Vss |j^ 


PAo 2 


PA, 3 


PAa A 


PA3 [7 


PA4 [T 


PA5 [7 


PAs 8 


PA7 9 


PBo 10 


PB, 11 


PBj 12 


PB3 13 


PB, 14 


PB5 16 


PBe 16 


PB7 17 


PB He 


TOD 19 


Vcc [m 



Ty- 



6526 



40 CNT 


m] sp 


m] RSo 


^ BS, 


38 RS2 


35 RS3 


34 1 RES 


33 DBo 


I2] DB, 


31 DB2 


30 DB3 


m| DB4 


28 DBs 


27 DBe 


26j DB7 


25 *2 


24 FLAG 


23] ^ 


22] R/W 



E 










Figure 16-19. 6526 CIA Pin Configuration 
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i ! 



I 1 



D0-D7 





DATA BUS BUFFERS 



SP ■• »> 



CNT 



TOD 



FLAG- 



IRQ 



SP 
BUFFER 



SERIAL 
PORT 



CNT 
BUFFER 



TOO 
BUFFER 



c 



V 



"N 



TOO/ 
AURM 



FUG 
BUFFER 



IRQ 
BUFFER 



***** 



c 



PRA 



DORA 



PA 
BUFFERS 



C > PA0-PA7 



INT/ 
MASK 



c 



PC 
BUFFER 



OORB 



PB 
BUFFERS 



TIMER B 



CRB 



TIMER A 



CRA 



CHIP ACCESS CONTROL 



lUiUll 



R/W 02 CS RS3 RS2 RSI RSO RES 

Figure 16-20. 6526 Block Diagram 



-»■ PC 



J> PBo-PBy 



ABSOLUTE MAXIMUM RATINGS 

Supply Voltage, Vcc 
Input/Output Voltage, Vjn 
Operating Temperature, Top 
Storage Temperature, Tstg 



-0.3V to +7.0V 

-0.3V to +7.0V 

0° C to 70° C 

-55° C to 150° C 
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All inputs contain protection circuitry to prevent damage due to high static 
discharges. Care should be exercised to prevent unnecessary application of voltages in 
excess of the allowable limits. 

COMMENT 

Stresses above those listed under "Absolute Maximum Ratings" may cause permanent 
damage to the device. These are stress ratings only. Functional operation of this device 
at these or any other conditions above those indicated in the operational sections of this 
specification is not implied and exposure to absolute maximum rating conditions for 
extended periods may affect device reliability. 



ELECTRICAL CHARACTERISTICS 
(Vcc ± 5%, Vss = V, Ta = 0-70°C) 



CHARACTERISTIC 


SYMBOL 


MIN. 


TYP. 


MAX. 


UNIT 


Input High Voltage 


Vffl 


+2.4 


— 


Vcc 


V 


Input Low Voltage 


Vn. 


-0.3 


— 


— 


V 


Input Leakage Current; 

Ve^ = Vss +5V 


IlN 




1.0 


2.5 


^lA 


(TOD, R/W, FLAG,<|)2, 
RES, RS0-RS3, CS) 




Port Input Pull-up Resistance 


Rpi 


3.1 


5.0 


— 


Kn 


Output Leakage Current for 
High Impedance State (Three 
State); Vns = 4V to 2.4V; 
(DB0-DB7, SP, CNT, IRQ) 


Itsi 




±1.0 


±10.0 


|xA 



Power Supply Current Ic, 



;c 



7 


10 


Pf 


7 


10 


pf 


70 


100 


mA 








1 



\A 



u 





Output High Voltage Vqh +2.4 — Vcc V 

Vcc = MIN,Iload<_ , 

-200fjiA (PA0-PA7, PC | 

PB0-PB7, DB0-DB7) -' 

Output Low Voltage Vql — — +0.40 V 

Vcc = MIN, Iload < 3.2 mA | 

Output High Current (Sourcing); Iqh -200 -1000 — (tA ^ 

VoH > 2.4V (PA0-PA7, _ 

PB0-PB7, PC, DB0-DB7 j [ 

Output Low Current (Sinking); Iql 3.2 — — mA Lj 

Vol < .4V (PA0-PA7, PC, 

PB0-PB7, DB0-DB7) Pl 

Input Capacitance Cin — 7 10 pf U 

Output Capacitance Cqut — 



u 



n- 



n 

! i 



( 1 
/ \ 



< I 



! I 



i I 
/ I 
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02 INPUT 



PERIPHERAL 
DATA OUT 



CS 

RS3-RS0 

R/W 



DATA IN 
DB7-OB0 



.y 



TCHW- 



■TcYC 

> 



'i 



3t 



Tads 



^: 



■ TwcS ■ 



tadh- 



■TrwS 



■fRWH- 



3: 



-Tds- 



Figure 16^21. 6526 Write Timing Diagram 



■ ^CLW ■ 



"TpD" 



/ 



^ 



Tom 



I I 



02 input 



i 


PORT IN 




es 


n 




1! 


flS3-RS0 




RAV 


r^ 




1 1 
1 \ 


DATA OUT 
D87-DB0 



.^ 



5t=zz 



Trws- * 



/ 



-Twcs- 



-Tads 



-TCO- 



•Tacc- 



Tadh- 



Trwm- 



3c 



:=^ 



Utdr-»I 



Figure 16-22. 6526 Read Timing Diagram 
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6526 INTERFACE SIGNALS 

())2— CLOCK INPUT 

The (|)2 clock is a TTL-compatible input used for internal device operation and as a timing 
reference for communicating with the system data bus. 

CS^HIP SELECT INPUT _ 

The CS input controls the activity of the 6526. A low level on CS while <t)2 is high causes 
the device to respond to signals on the R/W and address (RS) lines. A high on CS 
prevents these lines from controlling the 6526. The CS line is normally activated (low) 
at <j)2 by the appropriate address combination. 
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R/W— READ/WRITE INPUT 

The RAV signal is normally supplied by the microprocessor and controls the direction of 
data transfers of the 6526. A high on R/W indicates a read (data transfer out of the 
6526), while a low indicates a write (data transfer into the 6526). 

RS3-RS0^ADDRESS INPUTS 

The address inputs select the internal registers as described by the Register Map. 

DB7-DB0^DATA BUS INPUTS/OUTPUTS 

The eight data bus pins transfer information between the 6526 and the system data bus. 
These pins are high impedance inputs unless CS is low and R/W and ^2 are high to read 
the device. During this read, the data bus output buffers are enabled, driving the data 
from the selected register onto the system data bus. 

I^— INTERRUPT REQUEST OUTPUT 

IRQ is an open drain output normally connected to the processor inter rupt input. An 
external puUup resistor holds the signal high, allowing multiple IRQ outputs to be 
connected together. The IRQ output is normally off (high impedance) and is activated 
low as indicated in the functional description. 



RES— RESET INPUT 

A low on the RES pin resets all internal registers. The port pins are set as inputs and 
port registers to zero (although a read of the ports will return all highs because of 
passive pullups). The timer control registers are set to and the timer latches to all ones. 
All other registers are reset to 0. 
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6526 TIMING CHARACTERISTICS 
















CHARACTERISTIC 


IMHz 


2MHz 


UNIT 




SYMBOL 


MIN 


MAX 


MIN 


MAX 


~i 




<|)2 Clock 














TcYC 


Cycle Time 


1000 


20,000 


500 


20,000 


ns 


) 


Tr,Tf 


Rise and Fall Time 


— 


25 


— 


25 


ns 




TcHW 


Clock Pulse Width (High) 


420 


10,000 


200 


10,000 


ns 


K^ 


TcLW 


Clock Pulse Width (Low) 
Write Cycle 


420 


10,(M)0 


200 


10,000 


ns 


c 


TPD 


Output Delay From ({>2 


— 


1000 


— 


500 


ns 


Twcs 


CS low whUe (|)2 high 


420 


— 


200 


— 


ns 




Tads 


Address Setup Time 





— 





— 


ns 




Tadh 


Address Hold Time 


10 


— 


5 


— 


ns 




Trws 


R/W Setup Time 





— 





— 


ns 




Trwh 


R/W Hold Time 





— 





— 


ns 




Tds 


Data Bus Setup Time 


150 


— 


75 


— 


ns 


J 


Tdh 


Data Bus Hold Tune 





— 





— 


ns 



n 
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6526 TIMING CHARACTERISTICS (continued 

SYMBOL CHARACTERISTIC 


) 










) 1 


[Hz 


2MHz 




/ I 


MIN 


MAX 


MIN 


MAX 


UNIT 


(«i 




Read Cycle 












n 


Tps 


Port Setup Time 


300 





150 





ns 


1 j 


Twcs(2) 


CS low wliile (t>2 high 


420 


— 


20 


— 


ns 




Tads 


Address Setup Time 











.._ 


ns 


r~( 


Taoh 


Address Hold Time 


10 


^ 


5 


«» 


ns 


i ! 


Trws 


RAV Setup Time 











— . 


ns 




Trwh 


RAV Hold Time 





^_ 





_^ 


ns 




Tacc 


Data Access from RS3-RS0 


— . 


550 


^-. 


275 


ns 


n 


Ico(3) 


Data Access from CS 


^_ 


320 


^^ 


150 


ns 


1 \ 


Tdr 


Data Release Time 


50 


— 


25 




ns 



II 



n 



I ! 



I \ 



1 . All timings are referenced from Vil max and Vm min on inputs and Vol max and 
Vdh min on outputs. 

2. Twos is measured from the later of ^2 high or CS low. CS must be low at least 
until the end of ^2 high. 

3. Tco is measured from the later of <t)2 high or CS low. Valid data is available only 
after the later of Tacc or Tco- 



REGISTER MAP 



RS3 RS2 RSI RSO REG NAME 



DESCRIPTION 












PRA 








1 1 


PRB 





1 


2 


DDRA 





1 


1 3 


DDRB 





1 


4 


TALO 





1 


1 5 


TAHI 





1 1 


6 


TBLO 





1 1 


1 7 


TBHI 







8 


TOD lOTK 







1 9 


TOD SEC 




1 


A 


TOD MIN 




1 


1 B 


TODHR 




1 


C 


SDR 




1 


1 D 


ICR 




1 1 


E 


CRA 




1 1 


1 F 


CRB 



PERIPHERAL DATA REG A 
PERIPHERAL DATA REG B 
DATA DIRECTION REG A 
DATA DIRECTION REG B 
TIMER A LOW REGISTER 
TIMER A HIGH REGISTER 
TIMER B LOW REGISTER 
TIMER B HIGH REGISTER 
TOD lOTHS lOTHS OF SECONDS REGISTER 
SECONDS REGISTER 
MINUTES REGISTER 
HOURS— AM/PM REGISTER 
SERIAL DATA REGISTER 
INTERRUPT CONTROL REGISTER 
CONTROL REG A 
CONTROL REG B 
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6526 FUNCTIONAL DESCRIPTION 

I/O PARTS (PRA, PRB, DDRA, DDRB). 

Parts A and B each consist of an 8-bit Peripheral Data Register (PR) and an 8-bit Data 
Direction Register (DDR). If a bit in the DDR is set to one, the corresponding bit in the PR 
is an output; if a DDR bit is set to a 0, the corresponding PR bit is defined as an input. 
On a READ, the PR reflects the information present on the actual port pins (PA0-PA7, 
PB0-PB7) for both input and output bits. Port A and Port B have passive pull-up 
devices as well as active pull-ups, providing both CMOS and TTL compatibility. Both 
parts have two TTL load drive capability. In addition to normal I/O operation, PB6 and 
PB7 also provide timer output functions. 

HANDSHAKING _ 

Handsh aking on data transfers can be accomplished using the PC output pin and the 
FLAG input pin. PC will go low for one cycle following a read or write of PORT B. 
This signal can be used to indicate "data ready" at PORT B or "data accepted" from 
PORT B. Handshaking on 16-bit data transfers (usi ng both PORT A and PORT B) is 
possible by always reading or writing PORT_A first. FLAG is a negative edge sensitive 
input which can be used for receiving the PC output from a nother 6526 , or as a general 
purpose interrupt input. Any negative transition of FLAG will set the FLAG interrupt 
bit. 



REG NAME D, D« D, D4 D3 Dj D, D, 

PRA PA7 FAe PAj PA4 PAj PA2 PAj PAo 

1 PRB PB7 PBfi PBs PB4 PBj PB2 PBi PBo 

2 DDRA DPA7 DPA« DPAj DPA4 DPAj DPAj DPAj DPAo 

3 DDRB DPB7 DPB« DPBj DPB4 DPB3 DPB2 DPBi DPBo 



INTERVAL TIMERS (TIMER A, TIMER B) 

Each interval timer consists of a 16-bit read-only Timer Counter and a 16-bit write- 
only Timer Latch. Data written to the timer are latched in the Timer Latch, while 
data read from the timer are the present contents of the Time Counter. The timers 
can be used independently or linked for extended operations. The various timer modes 
allow generation of long time delays, variable width pulses, pulse trains and variable ) 

frequency waveforms. Utilizing the' CNT input, the timers can count external pulses * 

or measure frequency, pulse width and delay times of external signals. Each timer 
has an associated control register, providing independent control of the following 
fiinctions: 



START/STOP 

A control bit allows the timer to be started or stopped by the microprocessor at any 
time. 



u 



u 



i f 

1-^ 



i 
u 



u 






u 



u 



n 



{ ) 
/ 1 



i ! 
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PB ON/OFF 

A control bit allows the timer output to appear on a PORT B output line (PB6 for 
TIMER A and PB7 for TIMER B). This function overrides the DDRB control bit and 



t \ forces the appropriate PB line to an output. 

TOGGLE/PULSE 

A control bit selects the output applied to PORT B. On every timer underflow the output 
can either toggle or generate a single positive pulse of one cycl e dura tion. The toggle 
^ output is set high whenever the timer is started and is set low by RES. 

I ! ONE-SHOT/CONTINUOUS 

A control bit selects either timer mode. In one-shot mode, the timer will count down 
n from the latched value to 0, generate an interrupt, reload the latched value, then stop. In 

} I continuous mode, the timer will count from the latched value to 0, generate an interrupt, 

reload the latched value and repeat the procedure continuously. 

n FORCE LOAD 

I I A strobe bit allows the timer latch to be loaded into the timer coimter at any time, 

whether the timer is running or not. 

P\ INPUT MODE 

Control bits allow selection of the clock used to decrement the timer. TIMER A can 
count <(>2 clock pulses or external pulses applied to the CNT pin. TIMER B can count <^2 

j j pulses, external CNT pulses, TIMER A underflow pulses or TIMER A underflow pulses 

' ' while the CNT pin is held high. 

The timer latch is loaded into the timer on any timer underflow, on a force load or 

p following a write to the high byte of the prescaler while the timer is stopped. If the timer 

I \ is running, a write to the high byte will load the timer latch, but not reload the counter. 

n READ (TIMER) 

J 

REG NAME 

r-, 4 TALO TAL, TAL« TALj TAL4 TAL3 TAL2 TAL, TALo 

\\ 5 TAHI TAH7 TAHj TAHj TAH4 TAH3 TAH2 TAH, TAHo 

! ^ 6 TBLO TBL7 TBLs TBLj TBL4 TBL3 TBL2 TBLi TBLo 

7 TBHI TBH7 TBHfi TBH5 TBH4 TBH3 TBH2 TBHi TBHo 



WRITE (PRESCALER) 

REG NAME 

4 TALO PAL7 PALs PALj PAL4 PAL3 PAL2 PAL, PALo 

5 TAHI PAH7 PAH« PAHs PAH4 PAH3 PAH^ PAHj PAHo 

6 TBLO PBL7 PBLs PBLj PBL4 PBL3 PBL2 PBL, PBLo 

7 TBHI PBH7 PBH« PBHs PBH4 PBH3 PBH2 PBH, PBHo 
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u 

TIME OF DAY CLOCK (TOD) ^ 

The TOD clock is a special purpose timer for real-time applications. TOD consists of a 
24-hour (AM/PM) clock with 1/lOth second resolution. It is organized into four regis- | / 

ters: lOths of seconds, Seconds, Minutes and Hours. The AM/PM flag is in the MSB of [_, 

the Hours register for easy bit testing. Each register reads in BCD format to simplify 
conversion for driving displays, etc. The clock requires an external 60 Hz or 50 Hz | ; 

(programmable) TTL level input on the TOD pin for accurate time keeping. In addition 
to timekeeping, a programmable ALARM is provided for generating an interrupt at a 
desired time. The ALARM registers are located at the same addresses as the correspond- 
ing TOD registers. Access to the ALARM is governed by a Control Register bit. The 
ALARM is write-only; any read of a TOD address will read time regardless of the state 
of the ALARM access bit. 

A specific sequence of events must be followed for proper setting and reading of 
TOD. TOD is automatically stopped whenever a write to the Hours register occurs. The 
clock will not start again until after a write to the lOths of seconds register. This assures 
TOD will always start at the desired time. Since a carry from one stage to the next can 
occur at any time with respect to a read operation, a latching function is included to 
keep all Time Of Day information constant during a read sequence. All four TOD 
registers latch on a read of Hours and remain latched until after a read of lOths of 
seconds. The TOD clock continues to count when the output registers are latched. If 
only one register is to be read, there is no carry problem and the register can be read 
"on the fly," provided that any read of Hours is followed by a read of lOths of seconds 
to disable the latching. 



READ 














REG NAME 














8 TODIOTHS 








Tg 


T4 


T2 


Ti 


9 TOD SEC 


SH4 SH2 


SHi 


SLg 


SL4 


SL2 


SLi 


A TOD MIN 


MH4 MH2 


MHi 


MLg 


MI,i 


ML2 


MLi 


B TOD HR PM 





HH 


HLg 


HL4 


HL2 


HLi 






u 



) I 



WRITE \ 

CRB7 = 0TOD 

CRB7 = 1 ALARM 

(SAME FORMAT AS READ) | 

SERIAL PORT (SDR) , , 

The serial port is a buffered, 8-bit synchronous shift register system. A control bit jj 

selects input or output mode. In input mode, data on the SP pin is shifted into the shift 

register on the rising edge of the signal applied to the CNT pin. After eight CNT pulses, 

the data in the shift register is dumped into the Serial Data Register and an interrupt is \ J 

generated. In the output mode, TIMER A is used for the baud rate generator. Data is U 



I I 



! 1 
I , 
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shifted out on the SP pin at one half the underflow rate of TIMER A. The maximum 
baud rate possible is ^2 divided by 4, but the maximum useable baud rate will be 
determined by line loading and the speed at which the receiver responds to input data. 

/ J Transmission will start following a write to the Serial Data Register (provided TIMER A 

is running and in continuous mode). The clock signal derived from TIMER A appears as 
an output on the CNT pin. The data in the Serial Data Register will be loaded into the 
shift register then shift out to the SP pin when a CNT pulse occurs. Data shifted out 
becomes valid on the falling edge of CNT and remains valid until the next falling edge. 
After eight CNT pulses, an interrupt is generated to indicate more data can be sent. If 
the Serial Data Register was loaded with new information prior to this interrupt, the new 
data will automatically be loaded into the shift register and transmission will continue. If 
the microprocessor stays one byte ahead of the shift register, transmission will be 
continuous. If no further data is to be transmitted, after the 8th CNT pulse, CNT will 
return high and SP will remain at the level of the last data bit transmitted. SDR data is 
shifted out MSB first and serial input data should also appear in this format. 

The bidirectional capability of the Serial Port and CNT clock allows many 6526 
devices to be connected to a common serial conmiunication bus on which one 6526 acts 
as a master, sourcing data and shift clock, while all other 6526 chips act as slaves. Both 
CNT and SP outputs are open drain to allow such a common bus. Protocol for 

p master/slave selection can be transmitted over the serial bus, or via dedicated handshaking 

I I lines. 



! I 
/ i 



f 1 
I \ 



i! 



n 
I i 



REG NAME 

C SDR S7 St Ss S4 S3 S2 Si So 



I \ 

INTERRUPT CONTROL (ICR) 

r^ There are five sources of interrupts on the 6526: underflow fr om TIM ER A, underflow 

1 I from TIMER B, TOD ALARM, Serial Port full/empty and FLAG. A single register 

provides masking and interrupt information. The interrupt Control Register consists of a 

f^ write-only MASK register and a read-only DATA register. Any interrupt will set the 

i 1 corresponding bit in the DATA register. Any interrupt which is enab led b y the MASK 

^ register will set the IR bit (MSB) of the DATA register and bring the IRQ pin low. In a 

multi-chip system, the IR bit can be polled to detect which c hip h as generated an 
r] interrupt request. The interrupt DATA register is cleared and the IRQ line returns high 

/ I following a read of the DATA register. Since each interrupt sets an interrupt bit 

regardless of the MASK, and each interrupt bit can be selectively masked to prevent the 
f-) generation of a processor interrupt, it is possible to intermix polled interrupts with true 

j j interrupts. However, polling the IR bit will cause the DATA register to clear, therefore, 

it is up to the user to preserve the information contained in the DATA register if any 

polled interrupts were present. 
n The MASK register provides conven ient cont rol of individual mask bits. When 

'• i writing to the MASK register, if bit 7 (SET/CLEAR) of the data written is a ZERO, any 
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mask bit written with a one will be cleared, while those mask bits written with a 
will be unaffected. If bit 7 of the data written is a ONE, any mask bit written with a one 
will be set, while those mask bits written with a will be unaffected. In order for an 
interrupt flag to set IR and generate an Interrupt Request, the corresponding MASK bit 
must be set. 



READ (INT DATA) 

REG NAME 

D ICR IR 



FLG SP ALRM TB TA 



WRITE (INT MASK) 

REG NAME 

D ICR S/C X X FLG SP ALRM TB TA 



U 



Ll 



CONTROL REGISTERS 

There are two control registers in the 6526, CRA and CRB. CRA is associated 
with TIMER A and CRB is associated with TIMER B. The register format is as 
follows: 



U 



U 



CRA: 






BFT NAME 



START 



PEON 
OUTMODE 
RUNMODE 
LOAD 



5 INMODE 

6 SPMODE 

7 TODIN 



FUNCTION 

1 = START TIMER A, = STOP TIMER A, This bit is automat- 
ically reset when underflow occurs during one-shot mode. 
1 = TIMER A output appears on PB6, 0=PB6 normal operation. 
1 = TOGGLE, 0= PULSE 
1 = ONE-SHOT, = CONTINUOUS 

1 = FORCE LOAD (this is a STROBE input, there is no data 
storage, bit 4 will always read back a and writing a has no 
efl^ect). 

1 = TIMER A counts positive CNT transitions, = TIMER A counts 
(|)2 pulses. 

1 = SERIAL PORT output (CNT sources shift clock), = SERIAL 
PORT input (external shift clock required). 
1 = 50 Hz clock required on TOD pin for accurate time, = 60 Hz 
clock required on TOD pin for accurate time. 



u 



u 

y 
u 



n 
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CRB: 



/ \ 



II 



I i 



n 
/ \ 



BIT NAME 



5,6 INMODE 



7 ALARM 



FUNCTION 

(Bits CRB0-CRB4 are identical to CRA0-CRA4 for TIMER B 

witli the exception tliat bit 1 controls tlie output of TIMER B on 

PB7). 

Bits CRBS and CRB6 select one of four input modes for TIMER 

B as: 



CRB6 





1 

1 



CRBS 



1 



1 



TIMER B counts ^2 pulses. 

TIMER B counts positive CNT transitions. 

TIMER B counts TIMER A underflow pulses. 

TIMER B counts TIMER A underflow pulses 

while CNT is high. 
l = writuig to TOD registers sets ALARM, 0=writfaig to TOD 
registers sets TOD clock. 



n 
' 1 



KEG 


NAME 


TOD 
IN 


SP 
MODE 


IN 
MODE 


U>AD 


RUN 
MODE 


OUT 
MODE 


PS ON 


START 


E 


CRA 


0=60Hz 
l°50Hz 


0=INPOT 
1=0UTPUT 


= (t.2 

I=CNT 


I = FORCE 

LOAD 
(STROBE) 


0=CONT 
1=0.5 


0= PULSE 
1= TOGGLE 


0=PB6OFF 
l=PB«ON 


0=STOP 
1=START 



-TA- 



! i 



REG 


NAME 


ALARM 


IN 


MODE 


LOAD 


RUN 
MODE 


OUT 
MODE 


PS ON 


START 


F 


CRS 


= TOD 

1 = 
ALARM 




1 
1 


= <|>2 

I=CNT 

0=TA 

1=CNTTA 


1 = FORCE 
LOAD 

(STROBE) 


= CONT. 
l=O.S. 


0=PULSE 
1= TOGGLE 


o=PS70Fr 

I^PStON 


= STOP 
1=START 



-TB- 



All unused register bits are unaffected by a write and are forced to zero on a 
read. 
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DYNAMIC RANDOM ACCESS 

MEMORY I 

This section discusses the characteristics of the C128 dynamic RAMs, which are 

currently the 4164 64K-bit RAM. This RAM device is in the 64K by 1-bit configura- j { 

tion. This section also contains information on the 4416 dynamic RAMs used by 

the 8563 video controller. This type of RAM is a 64K RAM in the 16K by 4 bit 

configuration. 



I 



cJ 



i I 



\ ! 







SYSTEM RAM DESCRIPTION 

The C128 system contains 128K of processor-addfessable DRAM in the 64K by 1 
configuration, organized into two individual 64K banks. Additionally, the system 
contains 16K of video display DRAM local to the 8563 video controller, not directly 
accessable by the processor. i j 

RAM banking, described in detail in the MMU section in Chapter 13, is controlled '^ 

by several MMU registers: the Configuration Register, the RAM Configuration Regis- 
ter, and the Zero Page and Page One Pointers. Simply put, the Configuration Register 
controls which 64K bank of RAM is selected; the RAM Configuration Register controls 
if and how much RAM is kept in conunon between banks, and the Pointer Registers 
redirect the zero and one pages to any page in memory, overriding the effect of the two ^ 

Configuration Registers. In the system, RAM bank select is achieved via gated CAS j 

control. 

PHYSICAL CHARACTERISTICS U 

This section covers some of the characteristics of the 64K by 1-bit RAM and 16K by 

4-bit RAM that are used in the C128 system. A pinout table and a figure are given for ) 

both the 4164 and the 4416 packages (See Tables 16-15 and 16-16 and Figures 16-23 and '— ' 

16-24). 



ii 



u 



u 
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n 



PIN 


NAME 


DESCRIPTION 


1 


NC 


No Connection 


2 


Du, 


Data In 


3 


AVE 


Write Enable (Active Low) 


4 


/RAS 


Row Address Strobe (Active Low) 


5 


Ao 


Address Bit 


6 


A2 


Address Bit 2 


7 


Ai 


Address Bit 1 


8 


Vcc 


Power Supply +5 Vdc 


9 


A7 


Address Bit 7 


10 


As 


Address Bit 5 


11 


A4 


Address Bit 4 


12 


A3 


Address Bit 3 


13 


A« 


Address Bit 6 


14 


D„„, 


Data Out 


15 


/CAS 


Column Address Strobe (Active Low) 


16 


v„ 


Power Supply Ground 



Table 16-15. 4164 Pinout 




Figure 16-23. The 4164 Ciiip 
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PIN 


NAME 


DESCRlKliON 


1 


/OE 


Output Enable (Active Low) 


2 


D, 


Data Bit 1 


3 


D2 


Data Bit 2 


4 


AVE 


Write Enable (Active Low) 


5 


/RAS 


Row Address Strobe (Active Low) 


6 


A« 


Address Bit 6 


7 


As 


Address Bit 5 


8 


A4 


Address Bit 4 


9 


Vdd 


Power Supply +5 Vdc 


10 


At 


Address Bit 7 


11 


A3 


Address Bit 3 


12 


Ai 


Address Bit 2 


13 


Ai 


Address Bit 1 


14 


Ao 


Address Bit 


15 


Dj 


Data Bit 3 


16 


/CAS 


Column Address Strobe (Active Low) 


17 


D4 


Data Bit 4 


18 


Vss 


Power Supply Ground 



Table 16-16. 4416 PInout 




u 



\ I 
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u 



U 



Lj 



Figure 16-24. The 4464 Chip 



u 
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READ ONLY MEMORY (ROM) 

This section describes the C128 system ROM, both from a logical and a hardware point 
of view. It mentions aspects of the ROM banking structure, the management of Kemal 
and BASIC, and explains the physical specifications of the ROM devices themselves. 

SYSTEM ROM DESCRIPTION 

In C64 mode, the operating system resides in 16K of ROM, which includes approxi- 
mately 8K for Kemal and 8K for BASIC. In CI 28 mode, the operating system resides in 
48K of ROM and includes advanced Kemal and BASIC features. The Kemal, by 
i i defmition, is the general operating system of the computer, with fixed entry points into 

usable subroutines to facilitate ROM update transparent use by higher-level programs. 
There is also a character ROM that resides on the Shared Bus, shared by the VIC chip 
and the processor. This ROM is a 4016 8K by 8, NMOS ROM. The C64 OS ROM is 
wired so as to appear as two chunks of noncontiguous ROM, copying the actual C64 
ROM memory map. Provision is included to handle system ROM as either four 16K X 
8 ROMs or as two 32K x 8 ROMs. All internal C128 function ROMs will be the 32K 
X 8 variety. 

ROM BANKING 

Refer back to die MMU register map. Figure 13-4 in Chapter 13. Note that the 
Configuration Register (CR) controls the type of ROM or RAM seen in a given address 
location. Dependent on the contents of the CR, ROM may be enabled and disabled to 
attain the most useful configuration for the application at hand. ROM is enabled in three 
^ memory areas in C128 mode, each consisting of 16K of address space. The lower ROM 

I may be defined as RAM or System ROM, the upper two ROMs may be System ROM, 

' Function ROM, Cartridge ROM or RAM. In C64 mode, the C64 memory mapping mles 

apply, which are primitive compared to those used in C128 mode. C64 ROM is banked 
. as two 8K sections, BASIC and Kemal, according to the page zero port and the 

I cartridge in place at the time. No free banking can occur when a cartridge is in 

place. 

'» In the C128, if an address falls into the range of an enabled ROM, the MMU will 

I communicate the status of ROM to the PLA decoder via the memory status lines. 

Essentially, the MMU looks up in the Configuration Register which ROM or RAM is 

1 set. See Chapter 13. The way the banking scheme is implemented, it allows up to 32K 

I of intemal, bankable ROM for use in such programs as Function Key Applications, 

and will support 32K of intemal bankable ROM. Various combinations of ROM are 

possible, and can be noted by studying the configurations for the Configuration 

I Register. Type 23128 (16K by 8) and 23256 (32K by 8) ROMs are used by the 

system. 
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TIMING SPECIFICATION 

INTERNAL ROMs 

This section specifies timing parameters for both the 23128 and the 27256 Read Only 
Memories. This timing spec applies to internal ROMs and for external ROMs run at 1 
MHz. For external ROMs run at 2 MHz, see Table 16-18. 



PARAMETER 



SYMBOL 


MIN 


MAX 


UN 


Tacc 


300 


— 


ns 


TcE 


300 


— 


ns 


Toe 


120 


— 


ns 



Table 16-17. Internal ROM Timing 



RDDRESS- 



CHIP 
ENABLE 



OUTPUT 
ENRBLE 



DflTR 



" X X " 



Figure 16-25. ROM Timing Diagram 



EXTERNAL ROMS 

All C64 mode external ROMs and many CI 28 mode external ROMs can be of the type 
mentioned above. Any external ROM that is to run at 2 MHz must be faster, as 
specified in Table 16-18. 



Table 16-18. External 2MHz ROM Timing 



u 

I 

u 



) 

I 
I 



Address Valid to Output Delay 

Chip Enable to Output Delay 

Output Enable to Output Delay Tqe 120 — ns | ) 



I 
) 

U 



U 

u 
u 



u 



U 



II 



PARAMETER SYMBOL MIN MAX UNIT / 

Address Valid to Output Delay Tacc 250 — ns Lj 

Chip Enable to Output Delay Toe 200 — ns 

Output Enable to Output Delay Toe 100 — ns i 



u 
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THE 23128 ROM 



n 



i 



n 

n 



n 



PIN 


NAME 


DESCRIPTION 


1 


Vpp 


Programming Voltage 


2 


Al2 


Address Bit 12 (Au on tlie C64 OS ROM) 


3 


At 


Address Bit 7 


4 


A« 


Address Bit 6 


5 


As 


Address Bit 5 


6 


A4 


Address Bit 4 


7 


A3 


Address Bit 3 


8 


A2 


Address Bit 2 


9 


A, 


Address Bit 1 


10 


Ao 


Address Bit 


11 


Do 


Data Bit 


12 


D, 


Data Bit 1 


13 


D2 


Data Bit 2 


14 


GND 


Power Supply Ground 


15 


D3 


Data Bit 3 


16 


D4 


Data Bit 4 


17 


Ds 


Data Bit 5 


18 


D« 


Data Bit 6 


19 


D7 


Data Bit 7 


20 


/CE 


Chip Enable (Active Low) 


21 


Aio 


Address Bit 10 


22 


/OE 


Output Enable (Active Low) 


23 


A„ 


Address Bit 11 


24 


As 


Address Bit 9 


25 


Ag 


Address Bit 8 


26 


A,3 


Address Bit 13 


27 


/PGM 


Program Enable (Active Low) 


28 


Vcc 


Power Supply +5 Vdc 



Table 16-19. 23128 ROM Pinout 



n 
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Figure 16-26. The 23128 ROM Chip (BASIC. Kemal. Editor and External Function 
ROMs) 
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THE 23256 ROM 



n 
n 

n 



n 



n 
n 

n 
n 

n 

n 
n 
n 



PIN 


NAME 


DESCRIPTION 


1 


Vpp 


Programming Voltage 


2 


A,2 


Address Bit 12 


3 


At 


Address Bit 7 


4 


A« 


Address Bit 6 


5 


As 


Address Bit 5 


6 


A4 


Address Bit 4 


7 


A3 


Address Bit 3 


8 


A2 


Address Bit 2 


9 


A, 


Address Bit 1 


10 


A« 


Address Bit 


11 


Do 


Data Bit 


12 


D, 


Data Bit 1 


13 


D2 


Data Bit 2 


14 


GND 


Power Supply Ground 


15 


D3 


Data Bit 3 


16 


D4 


Data Bit 4 


17 


Ds 


Data Bit 5 


18 


D6 


Data Bit 6 


19 


D7 


Data Bit 7 


20 


/CE-/PGM 


Cliip Enable-Program Enable (Active Low) 


21 


Aio 


Address Bit 10 


22 


/OE 


Output Enable (Active Low) 


23 


A„ 


Address Bit 11 


24 


A, 


Address Bit 9 


25 


Ag 


Address Bit 8 


26 


A,3 


Address Bit 13 


27 


Am 


Address Bit 14 


28 


V.C 


Power Supply +5 Vdc 



Table 16-20. 23256 ROM Pinout (Internal or External Function ROMs) 
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Figure l«-27. The 232S« ROM Chip 
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THE SERIAL BUS 



! [ The C128 Serial Bus is an improved version of the C64 serial bus. This bus uses 

IEEE-488-type addressing, thus maintaining software compatibility between the con- 
p sumer market serial devices and the CBM IEEE-488 parallel devices. The C128 

I I improves this bus by allowing conmiunication at much greater speeds with specially 

designed peripherals, the most important being the disk drive, while still maintaining 
_ compatibility with older, slower peripherals used by the C64. This section describes the 

j I hardware and some of the software aspects of both the old and the new serial transmis- 

sion scheme. 

n BUS OPERATIONS 

n There are three basic bus operations that take place on the serial bus, in both fast and 

slow modes. The first of these is called Control. The C128 is the controller in most 
circumstances. The controller of the bus is always the device that initiates protocol on 
the bus, requesting peripheral devices to do one of the two other serial operations, either 
"I Talk or Listen. 

All serial bus devices can listen. A listening device is a device that has been 
ordered by the controller to receive data. Some devices, such as disk drives, can talk. A 
talking device is sending data to the controller. Both hardware and software drive this 
bus protocol. 

n BUS SIGNALS 

The Commodore serial bus is composed of the following signals: 

n ■ SRQ (pin 1): This signal is called Service Request. The slow serial bus does 

not use this line, the fast bidu-ectional clock line. (Not used in C64 Mode.) 

■ GND (pin 2): Chassis ground. 

~\ ■ ATN (pin 3): This signal is called Attention. It is used to address a device on 

the bus. When requesting a device to talk to or listen, the controller brings this 
signal low, creating some sort of interrupt on all serial bus devices. It then 
sends out an address that will select one device on the bus. It is the controller's 
responsibility to time out if a device on the bus does not respond within a 
reasonable amount of time. 

n" CLK (pin 4): This is the slow serial clock. It is used by slow serial devices, 
which are software-clocked, to clock data transmitted on the serial bus. 

■ DATA (pin 5): This is the serial data line. It is used by both slow and fast 
serial devices to transmit data in sync with clock signal. 

n ■ RESET (pin 6): This is the reset line, used to reset all peripherals when the 

' ' host resets. 
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FAST SERIAL BUS 



U 

u 



FAST PROTOCOL I 

To function as a fast talker, the system must be addressing a fast device, such as the U 

1571 disk drive. When addressing any device, the C128 sends a fast byte, toggling the 

SQR line eight times, with the ATN line low. If the device is a fast device, it will record j ' 

the fact that a fast controller accessed it and respond with a fast acknowledge. If the |_ 

device is a slow device, no response is delivered and the C128 then assumes it is talking 

with a slow device. The status of drive speed is retained until the device is requested to 

untalk or unlisten, if an error occurs, or if a system reset occurs. 

FAST HARDWARE 

The fast serial bus, in order to achieve its speed increase, uses different hardware from I 

that of the slow serial bus. The slow serial bus uses several 6526 port lines to drive L 

ATN, CLK and DATA. Thus, clocking of the data transfers must be software-driven. 

The fast serial method is to use the serial port line of a 6526 (CIA-1) to actually transfer , 

the serial data. This increases the transfer rate dramatically, to the point where the i 

transfer becomes limited more by software overhead than anything else. The actual 

speed of transfer is set by the 6526 timer. Current 6526's have a minimum serial timer 

value of 4, though in actual use this value is closer to 6, owing to loading. Any 

advances in the 6526 would make a faster data transfer possible. 1— 

This scheme could interfere with slow serial transmissions, since the DATA line is 
shared by both schemes. Thus, circuitry exists that will isolate the fast serial drivers 
from the slow serial bus. Setting FSDIR to input mode is sufficient to remove any 
possible fast serial interactions with the slow serial bus, other than the additional device 
loading, which is not a problem at slow serial bus speeds. 

In order to ensure compatibility with the C64, however, the slow serial bus cannot 
interfere with the fast drivers, since these drivers are shared with the User Port and a 
user port device could presumably make use of them. Once C64 mode is set, the input 
direction of the interface circuitry is disabled. Thus, in C64 mode, the FSDIR bit must 
be set to input to remove fast to slow interference, but slow to fast interference is 
automatically removed by invoking C64 mode. There is no way to disable slow to fast 
interference in CI 28 mode (at least not simultaneously with the elimination of fast to 
slow interference). [_ 
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THE EXPANSION BUS 

The CI 28 Expansion Bus is compatible with the C64 Expansion Bus, while at the same 
time allowing extended capabilities in C128 mode. 

CARTRIDGE ADDITION 

The C128 can use larger and more sophisticated cartridges than the C64. One of the 
main reasons for this is the new banking scheme used in the C128 for external 
cartridges. The C64 uses two hardware control lines, /EXROM and /GAME, to control 
banking out of internal facilities and banking in of cartridge facilities. The CI 28 uses a 
n software polling method, where upon power-up it polls the cartridge, according to a 

! ! defined protocol, to determine if such a cartridge exists, and if so, what its software 

priority is. Since the C128 is always free to bank between cartridges and built-in ROM, 
an external application can take advantage of internal routines and naturally become an 
extended part of the C128, as opposed to becoming a replacement application. See 
Chapter 13 for information on the Auto Start Cartridge ROM sequence. 

The elimination of /EXROM and /GAME as hardware control lines for cartridge 
identification (in C128 mode) has freed up both of these lines for extended functioning. 
Both of the lines appear as bits in the MMU Mode Configuration Register, and are both 
input and output ports. Neither has a dedicated function other than general cartridge 
function expansion, and lend themselves to act as latched banking lines or input sense 
lines. Of course, neither can be asserted on C128 power-up or C64 mode will automati- 
cally be set. 

DMA CAPABILITY 

The C128 expansion bus supports DMAs in a fashion similar to that of the C64. A C64 
DMA is achieved by pulling the /DMA pin on the expansion bus low. Immediately after 
this happens, the RDY and AEC lines of the processor are brought low. This can neatly 
shut down the processor, but it can also cause problems, depending on what the 
processor is doing at the time. The RDY input of an 8502 series processor, when brought 
low, will halt the processor of the next $1 cycle, leaving the processor's address lines 
reflecting the current address being fetched. However, if the processor is in a write cycle 
when RDY is brought low, it will ignore RDY until the next read cycle. Thus, in the 
C64, a /DMA input occurring during a write cycle will tri-state the processor's address 
and data bus, but not stop it until up to three cycles later when the next read cycle 
occurs. The write cycles following the /DMA input do not actually write, causing 
memory corruption and often processor fatality when the /DMA line is released. Any 
/DMA input during $2 is a potentially fatal DMA. 

If a proper /DMA is asserted, the C64 tri-states and shuts down, allowing the 
DMA source complete access to the processor bus. Such a DMA source must monitor 
the $2 and BA outputs, as it must tri-state when the VIC is on the bus, and it must 
completely DMA when a VIC DMA is called for. The VIC chip always has the highest 
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DMA priority. When on the bus, the DMA source has access to RAM, ROM and I/O 
in the C64 scheme. A proper DMA shutdown is usually achieved via some C64 software 
handshaking with the DMA source. j 

The C128 system uses a similar DMA scheme. When the /DMA input goes low, [_ 

the RDY input to the 8502, the AEC input to the 8502, and the /BUSRQST input to the 
Z80 inunediately go low. Additionally, the gated AEC signal, GAEC, goes low, , , 

causing the MMU to go immediately to its VIC CYCLE MODE, and the Z80 Data Out jj 

buffer to tri-state. The DMA causes the Address to the Shared Address buffer to reverse 
direction, and the Translated Address to the Address buffer to be enabled, giving the 
external DMA source complete access to the processor address bus. The PLA is still 
looking at ungated AEC and as such will allow access to I/O devices, RAM and ROM. 
There can be no access to the MMU; thus for CI 28 memory mapping the memory map 
must be set up before being DMA'ed. For C64 mode, memory mapping is done by the i i 

8502 processor port lines and by the external /EXROM and /GAME. Since the 8502 |J 

ports will be inaccessible by a DMA source, only the C64 map changes based upon 
/EXROM and /GAME can be made during a DMA. This is the same as m a C64 unit. 
All DMA sources, as with the C64, must yield to the VIC during $0 or BA low. The ] 

C 128 can perform a destructive DMA as easily as the C64. In order to use DMA's, the DMA ^ 

source will most likely have to cooperate with a C128 mode program, allowing it to 
handshake with a DMA source to effect DMA's nondestructively. j 

u 

u 
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EXPANSION BUS PINOUT 
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PIN 


NAME 


DESCRIPTION 


1 


GND 


System Ground 


2 


+5V 


System ¥„ 


3 


+ 5V 


System ¥„ 


4 


/IRQ 


Interrupt Request 


5 


R/W 


System Read Write Signal 


6 


DCLOCK 


8.18 MHz Video Dot Clocli 


7 


I/O, 


I/O Chip Select: $DE0O-$DEFF, Active Low 


8 


/GAME 


Sensed for Memory Map Configuration 


9 


/EXROM 


Sensed for Memory Map Configuration 


10 


I/O2 


I/O Chip Select: $DFOO-$D1<1<1 , Active Low. 


11 


/ROMl 


External ROM Chip Select, $8000-$BFFF in C128 Mode 
($8000-$9FFF in C64 mode) 


12 


BA 


Bus Available Output 


13 


/DMA 


Direct Memory Access Input (see caution on DMA capability 
on p. 636) 


14 


D7 


Data Bit 7 


IS 


D6 


Data Bit 6 


16 


Ds 


Data Bit 5 


17 


D4 


Data Bit 4 


18 


D3 


Data Bit 3 


19 


D2 


Data Bit 2 


20 


D, 


Data Bit 1 


21 


Do 


Data Bit 


22 


GND 


System Ground 


A 


GND 


System Ground 


B 


/ROMh 


External ROM Chip Select, $COOO-$FFFF in C128 Mode 
($COOO-$FFFF in C64 mode) 


C 


/RESET 


System Reset Signal 


D 


/NMI 


Non-Maskable Interrupt Request 


E 


IMHz 


System IMHz (^0 Clock 


F 


TAis 


Translated Address Bit 15 


H 


TA,4 


Translated Address Bit 14 


J 


TA,3 


Translated Address Bit 13 


K 


TA,2 


Translated Address Bit 12 


L 


TA„ 


Translated Address Bit 11 


M 


TAio 


Translated Address Bit 10 


N 


TA, 


Translated Address Bit 9 


P 


TAg 


Translated Address Bit 8 


R 


SA7 


Shared Address Bit 7 


S 


SA« 


Shared Address Bit 6 


T 


SAs 


Shared Address Bit 5 


U 


SAi 


Shared Address Bit 4 


V 


•SA3 


Shared Address Bit 3 


W 


SA2 


Shared Address Bit 2 


X 


SAi 


Shared Address Bit 1 


Y 


SAo 


Shared Address Bit 


Z 


GND 


System Ground 



Table 16-21. Expansion Bus Pinout 
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THE VIDEO INTERFACE 

The C128 VIC video interface hardware allows the connection of a standard NTSC or 
PAL commercial television and/or a color monitor. The monitor can accept either a 
composite video signal or separate chroma and luminance/sync signals in addition to an 
audio signal. This output is very similar to the output in later revision C64 units. 

The CI 28 also provides 80-column video interfacing. The available 80-column 
display is RGBI and monochrome, able to interface to most NTSC- or PAL-compatible 
RGBI TYPE I monitors and most 80-column-compatible NTSC or PAL monochrome 
monitors. 



u 



MONITOR OUTPUT 

The VIC video output provides the signals shown in Table 16-22. 



SIGNAL 


LEVEL 


IMPEDENCE 


DC OFFSET 


Luminance/Sync 


IV 


p-p 


75 ft 


0.5 V 


Chroma 


IV 


p-p 


75 ft 


0.5 V 


Composite 


IV 


p-p 


75 ft 


0.5 V 


Audio 


IV 


p-p 


IK ft 





Table 16-22. VIC Video Output Signals 



VIDEO CONNECTOR PINOUT 

The VIC video connector exists physically as an eight-pin DIN connector. It provides 
the signals shown in Table 16-23. 
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THE VIC VIDEO INTERFACE [\ 

The following items specify the VIC video interface for 40-column display in sixteen 

colors. The VIC signd is available at analog levels at the video connector and at RF i 

levels at the RF output. L 

MODULATOR SPECIFICATION , 

The modulator provides a broadcast-type RF signal carrying the VIC composite video j 

and audio signals. The NTSC modulator is switchable between channels 3 and 4 to help ^ 

minimize local broadcast interference. The signal generated by the RF modulator 
complies with the FCC ruling concerning FCC Class B, TV interface devices. The RF 
output is accessible via a standard RCA-type phono/video jack. 



u 



u 
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r-i 

1 
1 








PIN 


SIGNAL 


1 


1 

2 


Luminance/Sync 
Ground 




3 


Audio Out 


n 


4 

5 


Composite 
Audio In 


/ ( 


6 


Chroma 




7 


N.C. 


n 


8 


N.C. 



n 
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Table 16-23. Video Connector Signals 



THE 8563 VIDEO INTERFACE 



The following items specify the 8563 video interface for 80-column display in sixteen 
M colors. The 8563 signal is available at digital levels for RGBI and at a three-level 

' ' derived analog for black and white composite video. 

n MONITOR OUTPUT 

I I Table 16-24 shows the signals provided by the 8563 output. 



SIGNAL 


LEVEL 


IMPEDENCE 


Red 


TIL 


TTL 


Green 


TTL 


TTL 


Blue 


TIL 


TTL 


Intensity 


TTL 


TTL 


HSync 


TTL 


TTL 


VSync 


TTL 


TTL 


Composite 




75 ft 


Full Intensity 


2.0 V 




Half Intensity 


1.5 V 




Sync 


0.5 V 





Table 16-24. 8563 Output Signals 



VIDEO CONNECTOR PINOUT 

The 8563 video connector is an IBM-style D9 connector, providing the signals shown in 
Table 16-25. 
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PIN 


SIGNAL 


1 


Ground 


2 


Ground 


3 


Red 


4 


Green 


5 


Blue 


6 


Intensity 


7 


Monochrome (non-standard) 


8 


Horizontal Sync 


9 


Vertical Sync 



u 



u 



U 



Table 16-25. 8563 Video Connector Pinout 



THE KEYBOARD 

The CI 28 Keyboard is an advance over the standard C64 keyboard, while still maintain- 
ing full compatibility. It has several extra keys that are used in C128 mode, but not in 
C64 mode. It features a numeric keypad, a HELP key, extended function keys, a | j 

true CAPS LOCK key, and a 40/80 column switch key, all of which are U 

strobed by the VIC chip or tied to dedicated 8502 or MMU I/O lines. 

CONNECTOR PINOUT U 

The CI 28 keyboard is designed to be connected by one 12- and one 13-pin internal 
single-in-line connector for the unit with a built-in keyboard. Table 16-26 illustrates i 

both connections. ^ 
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D-TYPE SIGNAL 



1 


Ground 


2 


Key 


3 


Restore 


4 


+ 5V 


5 


Row 3 


6 


Row 6 


7 


Row 5 


8 


Row 4 


9 


Row 7 


10 


Row 2 


11 


Rowl 


12 


RowO 


13 


Column 


14 


Column 6 


15 


Column 5 


16 


Column 4 


17 


Column 3 


18 


Column 2 


19 


Column 1 


20 


Column 7 


21 


Ko 


22 


K, 


23 


K2 


24 


40/80 


25 


Alpha Lock 



I i 



Table 16-26. The Keyboard Connector PInout 
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THE CI 28 KEYBOARD TABLE 



RO 
PIN12 



Rl 
PINll 



R2 
PINIO 



R3 
PINS 



R4 
PINS 



R5 
PIN7 



R6 
PIN6 



R7 
PIN9 



CO 


CI 


C2 


03 


C4 


C5 


C6 


C7 


KO 


Kl 


K2 


PIN13 


PIN19 


PIN18 


PIN17 


PIN16 


PIN15 


PIN14 


PIN20 


PIN21 


PIN22 


PIN23 


INS 


# 


% 


* 


) 


+ 


lb 


£ 


HELP 


ESC 


ALT 


DEL 


3 


5 


7 


9 






1 








RET 


W 


R 


Y 


I 


P 


* 


«— 


8 


+ 





t 


A 


D 


G 


J 


L 


) 


CTRL 


5 


. 


, 


1 












> 










F8 


$ 


& 


( 





. 


CLR 


It 


TAB 


LINE 


t 


F7 


4 


6 


8 






HOM 


2 




FEED 


F2 


Z 


C 


B 


M 


> 


RIGHT 


SPACE 


2 


ENTER 


4 


Fl 










• 


SHIFT 


BAR 






F4 
F3 


S 


F 


H 


K 


[ 


= 




4 


6 


- 


F6 
F5 


E 


T 


U 





@ 


IT 


Q 


7 


9 


- 


«— 


LEFT 


X 


V 


N 


< 


1 


RUN 


1 


3 


NO 


-^ 


SHIFT 








* 


1 


STOP 






SCRL 



GND 
PIN-1 





SHIFT 
LOCK 








NMI 
PIN3 


« 


RESTR 








40/80 
PIN24 


< 


40/80 
DSPLY 








P6510 
PIN2S 


< 


CAPS 
LOCK 



/ (LOCKING) 



/ (LOCKING) 



/ (LOCKING) 



NOTE: Pins RO through R7 pertain to the keyboard row values for the keyboard SCAN. 
These pins correspond to bits through 7 of location 56321 (SDCOl). 

Pins CO through C7 are the keyboard's column values, which correspond to bits 
through 7 of location 56320 ($DC0O). 

Pins KO through K2 pertain to the C128 keyboard control register bit, through 2 of 
location 53295 ($D02F). 
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APPENDIX A 
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BASIC LANGUAGE 
ERROR MESSAGES 

The following error messages are displayed by BASIC. Error messages can also be 
displayed with the use of the ERR$() function. The error numbers below refer only to 
the number assigned to the error for use with the ERR$() function. 



ERROR # ERROR NAME 

1 TOO MANY FILES 

2 FILE OPEN 

3 HLE NOT OPEN 

4 HLE NOT FOUND 

5 DEVICE NOT PRESENT 

6 NOT INPUT FILE 

7 NOT OUTPUT HLE 

8 MISSING FILE NAME 

9 ILLEGAL DEVICE NUMBER 

10 NEXT WITHOUT FOR 

11 SYNTAX 



DESCRIPTION 

There is a limit of ten files OPEN at one 
time. 

An attempt was made to open a file using 
the number of an already open file. 

The file number specified in an I/O state- 
ment must be opened before use. 

Either no file with that name exists (disk) 
or an end-of-tape marker was read (tape). 

The required I/O device is not available or 
buffers deallocated (cassette). Check to make 
sure the device is connected and turned 
on. 

An attempt was made to GET or INPUT 
data from a file that was specified as output 
only. 

An attempt was made to send data to a file 
that was specified as input only. 

File name missing in command. 

An attempt was made to use a device im- 
properly (SAVE to the screen, etc.). 

Either loops are nested incorrectly, or diere 
is a variable name in a NEXT statement 
that doesn't correspond with one in FOR. 

A statement not recognized by BASIC. This 
could be because of a missing or extra 
parenthesis, a misspelled key word, etc. 
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ERROR # ERROR NAME 

12 RETURN WITHOUT GOSUB 

13 OUT OF DATA 

14 ILLEGAL QUANTITY 

15 OVERFLOW 

16 OUT OF MEMORY 

17 UNDEF'D STATEMENT 

18 BAD SUBSCRIPT 

19 REDIM'D ARRAY 

20 DIVISION BY ZERO 

21 ILLEGAL DIRECT 

22 TYPE MISMATCH 

23 STRING TOO LONG 

24 HLE DATA 

25 FORMULA TOO COMPLEX 

26 CAN'T CONTINUE 

27 UNDEF'D FUNCTION 



DESCRIPTION 

A RETURN statement was encountered 
when no GOSUB statement was active. 

A READ statement is encountered without 
any data left to READ. 

A number used as the argument of a func- 
tion or statement is outside the allowable 
range. 

The result of a computation is larger than 
the largest number allowed (1.70141 1834E 
+ 38). 

Either there is no more room for program 
code and/or program variables, or there are 
too many nested DO, FOR or GOSUB state- 
ments in effect. 

A referenced line number doesn't exist in 
the program. 

The program tried to reference an element 
of an array out of the range specified by 
the DIM statement. 

An array can only be DIMensioned once. 

Division by zero is not allowed. 

INPUT, GET, INPUT#, GET# and GET- 
KEY statements are allowed only within a 
program. 

This error occurs when a numeric value is 
assigned to a string variable or vice versa. 

A string can contain up to 255 characters. 

Bad data read from a tape or disk file. 

The computer was unable to evaluate this 
expression. Simplify the expression (break 
into two parts or use fewer parentheses). 

The CONT conunand does not work if the 
program was not RUN, if there was an 
error, or if a line has been edited. 

A user-defined function that was never de- 
fined was referenced. 
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ERROR # ERROR NAME 

28 VERIFY 

29 LOAD 

30 BREAK 



31 
32 

33 
34 
35 

36 

37 
38 



39 



CAN'T RESUME 



LOOP NOT FOUND 



LOOP WITHOUT DO 



DIRECT MODE ONLY 



NO GRAPHICS AREA 



BAD DISK 



BEND NOT FOUND 



LINE NUMBER TOO LARGE 



UNRESOLVED REFERENCE 



40 



UNIMPLEMENTED 
COMMAND 



DESCRIPTION 

The program on tape or disk does not match 
the program in memory. 

There was a problem loading. Try again. 

The STOP command was issued in a pro- 
gram or the STOP key was pressed 
to halt program execution. 

A RESUME statement was encountered 
without a TRAP statement in effect. 

The program has encountered a DO state- 
ment and cannot find the corresponding 
LOOP. 

LOOP was encountered without a DO state- 
ment active. 

This command is allowed only in direct 
mode, not from a program. 

A command (DRAW, BOX, etc.) to create 
graphics was encountered before the 
GRAPHIC command was executed. 

An attempt failed to HEADER a diskette, 
because llie quick header method (no ID) 
was attempted on an unformatted diskette 
or the diskette is bad. 

The program encountered an "IF . . . THEN 
BEGIN" or "IF . . . THEN . . . ELSE 
BEGIN" construct, and could not find a 
BEND keyword to match the BEGIN. 

An error has occurred in renumbering a 
BASIC program. The given parameters re- 
sult in a line number greater than 63999 
being generated; therefore, the renumbering 
was not performed. 

An error has occurred in renumbering a 
BASIC program. A line number referred to 
be a conunand (e.g., GOTO 999) does not 
exist. Therefore, (he renumbering was not 
performed. 

A conmiand not supported by BASIC 7.0 
was encountered. 
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ERROR # ERROR NAME 
41 RLE READ 



DESCRIPTION 



An error condition was encountered while 
loading or reading a program or file from 
the disk drive (e.g., opening the disk drive 
door while a program was loading). 



I i 
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APPENDIX B 



DOS ERROR MESSAGES 



ERROR 

NUMBER ERROR MESSAGE AND DESCRIPTION 



22 





u 



The following DOS error messages are returned through the DS and DS$ variables. IKie IJ 

DS variable contains just the error number, and the DS$ variable contains the error 
number, the error message, and any corresponding track and sector number. NOTE: . , 

Error message numbers less than 20 should be ignored with the exception of 01, which jj 

gives information about the number of files scratched with the SCRATCH command. 



20 READ ERROR (block header not found) 
The disk controller is unable to locate the header of the requested data 
block. Causes: an illegal sector number, or the header has been destroyed. 

21 READ ERROR (no sync character) 
The disk controller is unable to detect a sync mark on the desired track. 
Causes: misalignment of the read/write head, no diskette, or an unformat- 
ted or improperly seated diskette. Can also indicate a hardware failure. 

READ ERROR (data block not present) | 

The disk controller has been requested to read or verify a data block that 
was not properly written. This error occurs in conjunction with the BLOCK 
conmiands and can indicate an illegal track and/or sector request. 
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23 READ ERROR (checksum error in data block) 
This error message indicates there is an error in one or more of the data 

bytes. The data has been read into die DOS memory, but the checksum 1 j 

over the data is in error. This message may also indicate hardware ground- L/ 

ing problems. 

24 READ ERROR (byte decoding error) | 
The data or header has been read into the DOS memory but a hardware *— ' 
error has been created owing to an invalid bit pattern in the data byte. This 
message may also indicate hardware grounding problems. 



n 



25 WRITE ERROR (write-verify error) 
This message is generated if the controller detects a mismatch between the 

written data and the data in the DOS memory. ) I 

26 WRITE PROTECT ON '-' 
This message is generated when the controller has been requested to write 
a data block while the write protect switch is depressed. This is caused by 
using a diskette with a write protect tab over the notch or a notchless diskette. 



u 
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ERROR 

NUMBER ERROR MESSAGE AND DESCRIPTION 

27 READ ERROR 

This message is generated when a checksum error has been detected in the 
header of the requested data block. The block has not been read into DOS 
r] memory. 

' ' 28 WRITE ERROR 

This error message is generated when a data block is too long and 
p, overwrites the sync mark of the next header. 

' * 29 DISK ID MISMATCH 

^ This message is generated when the controller has been requested to access 

i I a diskette that has not been initialized or improperly formatted. The 

message can also occur if a diskette has a bad header. 

30 SYNTAX ERROR (general syntax) 
The DOS cannot interpret the command sent to the command channel. 
Typically, fliis is caused by an illegal number of file names, or patterns 
that are illegally used. For example, two file names appear on the left side 
of the COPY command. 

31 SYNTAX ERROR (invalid command) 
The DOS does not recognize the command. The command must start in the 
first position. 

32 SYNTAX ERROR (invalid command) 
The command sent is longer than 58 characters. Use abbreviated disk 
conomands. 

33 SYNTAX ERROR (invalid file name) 
Pattern matching is invalidly used in the OPEN or SAVE command. Spell 
out the file name. 

34 SYNTAX ERROR (no file given) 
The file name was left out of the conmiand or the DOS does not recognize 
it as such. Typically, a colon(:) has been left out of the command. 

39 SYNTAX ERROR (invalid command) 

This error may result if the conmiand sent to the command channel 
(secondary address 15) is unrecognized by the DOS. 

50 RECORD NOT PRESENT 

Result of disk reading past die last record through INPUT# or GET# 
commands. This message will also appear after positioning to a record 
beyond end-of-file in a relative file. If the intent is to expand the file by 
adding the new record (with a PRINT# command), the error message may 
be ignored. INPUT# and GET# should not be attempted after this error is 
detected without first repositioning. 
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ERROR 

NUMBER ERROR MESSAGE AND DESCRIPTION 



51 OVERFLOW IN RECORD 

PRINT# statement exceeds record boundary. Information is truncated. 
Since the carriage return that is sent as a record terminator is counted in the 
record size, this message will occur if the total characters in the record 
(including the final carriage return) exceed the defined size of the record. 



Q 
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52 FILE TOO LARGE 

The record position within a relative file indicates that disk overflow will | { 

result. 

60 WRITE FILE OPEN 
This message is generated when a write file that has not been closed is 
being opened for reading. 

61 FILE NOT OPEN 
A file that has not been opened in the DOS is being accessed. Sometimes 
in this situation, a message is not generated; the request is simply ignored. 



U 
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62 FILE NOT FOUND 
The requested file does not exist on the indicated drive. 

63 FILE EXISTS 
The file name of the file being created akeady exists on the diskette. 

64 FILE TYPE MISMATCH |_ 
The requested file access is not possible using files of the type named. 

Reread the chapter covering that file type. 

65 NO BLOCK 
Occurs in conjunction with block allocation. The sector you tried to allocate 
is already allocated. The track and sector numbers returned are the next 
higher track and sector available. If the track number returned is 0, all 
remaining higher sectors are full. If the diskette is not full yet, try a 
lower track and sector. 

66 ILLEGAL TRACK AND SECTOR 
The DOS has attempted to access a track or a block that does not exist in 
the format being used. This may indicate a problem reading the pointer to 
the next block. 

67 ILLEGAL SYSTEM T OR S 
This special error message indicates an illegal system track or sector. 

70 NO CHANNEL (available) 

The requested channel is not available, or all channels are in use. A 
maximum of five buffers are available for use. A sequential file requires 
two buffers; a relative file requires three buffers; and the error/command 
channel requires one buffer. You may use any combination of those as 
long as the combination does not exceed five buffers. 
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ERROR 
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NUMBER 

71 


' ) 
/ 1 


72 



ERROR MESSAGE AND DESCRIPTION 

DIRECTORY ERROR 

The BAM (Block Availability Map) on the diskette does not match the 

copy on disk memory. To correct this, initialize the disk drive. 

DISK FULL 

Either the blocks on the diskette are used, or the directory is at its entry 
limit. DISK FULL is sent when two blocks are stiU available on the 
diskette, in order to allow the cunent file to be closed. 

73 DOS VERSION NUMBER (73, CBM DOS V30 1571, 00, 00) 

DOS 1 and 2 are read compatible but not write compatible. Disks may be 
interchangeably read with either DOS, but a disk formatted on one version 
cannot be written upon with the other version because the format is 
different. This error is displayed whenever an attempt is made to write 
p upon a disk that has been formatted in a noncompatible format. This 

( , message will also appear after power-up or reset and is not an error in this 

case. 

f] 74 DRIVE NOT READY 

' \ An attempt has been made to access the disk drive without a diskette 

inserted; or the drive lever or door is open. 

I i 
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CONNECTORS/PORTS FOR 
PERIPHERAL EQUIPMENT 



1. Power Socket 

2. Power Switch 

3. Reset Button 

4. Controller Ports 

5. Expansion Port 

6. Cassette Port 



7. Serial Port 

8. Composite Video Connector 

9. Channel Selector 

10. RF Connector 

11. RGBI Connector 

12. User Port 
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SIDE PANEL CONNECTIONS 
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1 . Power Socket — ^The free end of the cable from the power supply is attached here. 

2. Power Switch — ^Tums on power from the transformer. 

3. Reset Button — ^Resets computer (warm start). 

4. Controller Ports — ^There are two Controller ports, numbered 1 and 2. Each Con- 
troller port can accept a joystick mouse or a game controller paddle. A light pen 
can be plugged only into port 1, the port closest to the front of the computer. IFse 
the ports as instructed with the software. 



I \ 
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CONTROLLER PORT 1 



PIN TYPE 


NOTE 


f 1 2 3 4 5 


1 JOYAO 




\ O O O O O 


2 JOYAl 

3 JOYAl 

4 JOYA3 




\ O O O O / 
V^ 6 7 8 9 y 


5 POT AY 




6 BU 1 ION A/LP 






7 +5V 


MAX. 50inA 




8 GND 






9 POT AX 






CONTROLLER PORT 2 




PIN TYPE 


NOTE 




1 JOYBO 






2 JOYBl 






3 JOYBl 






4 J0YB3 






5 POT BY 






6 BU'lTON B 






7 +5V 


MAX. SOmA 




8 GND 






9 POT BX 







REAR CONNECTIONS 



i ! 
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5. Expansion Port— This rectangular slot is a parallel port that accepts program or 
game cartridges as well as special interfaces. 
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CARTRroCE 
EXPANSION PORT 



PIN 


TYPE 


PIN 


TYPE 


12 


BA 


1 


GND 


13 


DMA 


2 


+5V 


14 


D7 


3 


+ 5V 


15 


D6 


4 


ma 


16 


D5 


5 


RAV 


17 


D4 


6 


Dot Clock 


18 


D3 


7 


I/Ol 


19 


D2 


8 


GAME 


20 


Dl 


9 


EXROM 


21 


DO 


10 


I/O 2 


22 


GND 


11 


ROML 


PIN 


TYPE 


PIN 


TYPE 


N 


A9 


A 


GND 


P 


A8 


B 


ROMH 


R 


A7 


C 


RESET 


S 


A6 


D 


NMI 


T 


AS 


E 


S02 


U 


A4 


F 


A15 


V 


A3 


H 


A14 


W 


A2 


J 


A13 


X 


Al 


K 


A12 


Y 


AO 


L 


All 


Z 


GND 


M 


AlO 


22 21 »191» 17 16 1*14 1312 11 10 9 


8 7 8 5 4 3 2 1 





ZYXWVUTSRPNMLKJHFEOCBA 

(view of port from the back of the C128) 

Cassette Port— A 1530 Datassette recorder can be attached here to store programs 
and information. 

CASSETTE PORT 



1 2 3 4 S 6 



PIN 


TYPE 


A-1 


GND 


B-2 


+5V 


C-3 


CASSETTE MOTOR 


D-4 


CASSETTE READ 


E-5 


CASSETTE WRITE 


F-6 


CASSETTE SENSE 



A B C D E F 
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7. Serial Port — ^A Commodore serial printer or disk drive can be attached directly to 
the Commodore 128 through this port. 









SERIAL I/O PORT 



PIN 

1 
2 
3 
4 
5 
6 



TYPE 



SERIAL SRQIN 

GND 

SERIAL ATN IN/OUT 

SERIAL CLK IN/OUT 

SERIAL DATA IN/OUT 

RESET 




! I 



8. Composite Video Connector — ^This DIN connector supplies direct audio and com- 
posite video signals. These can be connected to the Conmiodore monitor or used 
with separate components. This is the 40-column output connector. 



!! 



/ \ 




(view of port while facing the rear of the C128) 



COMPOSITE VIDEO CONNECTOR 



PIN 


TYPE 


NOTE 


1 

2 


LUM/SYNC 
GND 


Luminance/SYNC output 


3 


AUDIO OUT 




4 

5 


VIDEO OUT 
AUDIO IN 


Composite signal output 


6 

7 


COLOR OUT 

NO 


Chroma signal output 
No connection 


8 


NC 


No connection 
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9. Channel Selector— Use this switch to select which TV channel (L = channel 3, H 
= channel 4) the computer's picture will be displayed on when using a television 
instead of a monitor. 

10. RF Connector— This connector supplies both picture and sound to your television 
set. (A television can display only a 40-column picture.) 

11. RGBI Connector— ^This 9-pin connector supplies direct audio and an RGB! (Red/ 
Green/ Blue/Intensity) signal. This is the 80-colunm output. 




RGBI CONNECTOR 



PIN 


SIGNAL 


1 


Ground 


2 


Ground 


3 


Red 


4 


Green 


5 


Blue 


6 


Intensity 


7 


Monochrome 


8 


Horizontal Sync 


9 


Vertical Sync 



12. User Port — ^Various interface devices can be attached here, including a Conmio- 
dore modem. 



u 
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USER I/O PORT 



! I 



I 1 



n 



PIN 


TYPE 






NOTE 


1 


GND 








2 


+ 5V 






MAX. lOOmA 


3 


RESET 








4 


CNTl 








5 


SPl 








6 


CNT2 








7 
8 


SP2 
PC2 








9 


SER. ATN IN 




10 


9 VAC 






MAX. lOOmA 


11 


9 VAC 






MAX. lOOmA 


12 


GND 









PIN 


TYPE 







NOTE 


A 


GND 








B 


FLAG2 








C 


PBO 








D 


PBl 








E 


PB2 








F 


PB3 








H 


PB4 








J 


PBS 








K 


PB6 








L 


PB7 








M 


PA2 








N 


GND 










12 3 4 


S 


6 7 


8 9 10 11 12 




■ ■ ■ ■ 


H 


-■-K. 


■ ■ ■ ■ ■ 


1 



ABCDEFHJKLMN 
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SCREEN DISPLAY CODES 

SCREEN DISPLAY CODES 
40 COLUMNS 

The chart below lists all the characters built into the Commodore screen character sets. 
It shows which numbers should be POKEd into the VIC chip (40-column) screen 
memory (location 1024 to 2023) to get a desired character on the 40-colunm screen. 
(Remember, to set color memory, use locations 55296 to 56295.) Also shown is which 
character corresponds to a number PEEKed from the screen. 

Two character sets are available. Both are available simultaneously in 80-column 
mode, but only one is available at a time in 40-column mode. The sets are switched by 
holding down the SHIFT and C* (Commodore) keys simultaneously. The entire 
screen of characters changes to the selected character set. 

From BASIC, PRINT CHR$(142) will switch to upper case/graphics mode and 
PRINT CHR$(14) will switch to upper/lower case mode. 

Any number on the chart may also be displayed in reverse. The reverse character 
code can be obtained by adding 128 to the values shown. 



SET1 


SET 2 


POKE 


8ET1 


SET 2 


POKE 


SET 1 SET 2 POKE 


@ 







N 


n 


14 


£ 


28 


A 


a 


1 








15 


1 


29 


B 


b 


2 


P 


P 


16 


t 


30 


C 


c 
d 

9 


3 
4 
5 


Q 

R 
S 


q 
r 

s 


17 

18 
19 


«- 


31 


D 


1 SPACE 


32 


E 


! 


33 


F 


f 


6 


T 


t 


20 


•• 


34 


G 


9 


7 


U 


u 


21 


# 


35 


H 


h 


8 


V 


V 


22 


$ 


36 


1 


i 


9 


w 


w 


23 


% 


37 


J 


J 


10 


X 


X 


24 


& 


36 


K 


k 


11 


Y 


y 


25 


' 


39 


L 


1 


12 


z 


z 


26 


( 


40 


M 


m 


13 


[ 




27 


) 


41 






u 



u 



u 
U 



u 



u 



n 
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SET1 


SET 2 POKE 


SET 1 SET 2 


POKE 


SET1 SET 2 


POKE 


* 


42 


D 


G 


71 


D 


100 


+ 


43 


□1 


H 


72 


D 


101 


1 


44 


^ 


1 


73 


m 


102 


— 


45 


V 


J 


74 


1 


103 


, 


46 


J 


K 


75 


u 


104 


/ 


47 


u 


L 


76 


B 


105 





48 


N 


M 


77 


n 


106 


1 


49 


V 


N 


78 


m 


107 


2 


50 


n 





79 


d 


108 


3 


51 


□ 


P 


80 


m 


109 


4 


52 


H 


Q 


81 


b. 


110 


5 


53 


u 


R 


82 


^ 


111 


6 


54 


¥ 


S 


83 


Ld 


112 


7 


55 


II 


T 


84 


^ 


113 


8 


56 


f 


U 


85 


H 


114 


9 


57 


^ 


V 


86 


m 


115 


* 


58 


o 


w 


87 


D 


116 


t 


59 


1*1 


X 


88 


1 


117 


< 


60 


1 


Y 


89 


[] 


118 


= 


61 


[fi 


z 


90 


r" 


119 


> 


62 


ffl 




91 


n 


120 


? 


63 


n 




92 


u 


121 


h 


64 


1 




93 


J ^ 


122 


♦ 


A 65 


TT K 


94 


b! 


123 


m 


B 66 
C 67 
D 68 


a 


ss 


95 
96 
97 


J 


124 


H 


1 SPACE 


125 


-1 


1 


126 


H 


E 69 


y 




98 


H 


127 


U 


F 70 


n 




99 







Codes from 128-255 are reversed Images of codes 0-127. 
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ASCII AND CHR$ CODES 

This appendix shows you what characters will appear if you PRINT CHR$(X), for all 
possible values of X. It also shows the values obtained by typing PRINT ASC ("x"), 
where x is any character that can be displayed. This is useful in evaluating the character 
received in a GET statement, converting upper to lower case and printing character- 
based commands (such as switch to upper/lower case) that could not be enclosed in 
quotes. 



PRINTS CHRS 


PRINTS 


CHR$ 


PRINTS 


CHRS 


PRINTS 


CHRS 







23 




46 


E 


69 


1 




24 


/ 


47 


F 


70 


2 




25 





48 


G 


71 


3 




26 


1 


49 


H 


72 


4 




27 


2 


50 


1 


73 


^^^k 5 


ask 


28 


3 


51 


J 


74 


6 


B 


29 


4 


52 


K 


75 


7 


^1^ 


30 


5 


53 


L 


76 


OISABLES^QQS 


^^ 


31 


6 


54 


M 


77 


ENABLES ^QQg 


gg 


32 


7 


55 


N 


78 


10 


! 


33 


8 


56 





79 


11 


" 


34 


9 


57 


P 


80 


12 


# 


35 


: 


58 


Q 


81 


^^^^Q 13 


$ 


36 


1 


59 


R 


82 




% 


37 


<Z 


60 


S 


83 


15 


& 


38 


= 


61 


T 


84 


16 


• 


39 


I> 


62 


U 


85 


g 17 


( 


40 


? 


63 


V 


86 


^^ 18 


) 


41 


@ 


64 


w 


87 


M 19 


• 


42 


A 


65 


X 


88 


Q 20 


+ 


43 


B 


66 


Y 


89 


21 


* 


44 


C 


67 


z 


90 


22 


- 


45 





68 


[ 


91 



n 
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PRINTS 


CHRI 


PRINTS 


CHRt 


PRINTS CHRS 


PRINTS CNRI 1 


£ 


92 


[!?l 


115 


f4 138 


D ^ 


161 


1 


93 


r 


116 


f6 139 


H ^ 


162 


T 


94 


c 


117 


f8 140 


n ' 


163 


,_ 


95 


X 


118 


^ffl|QflQ[Q^41 


J ■ 


164 


H 


96 


o 


119 


Nni42 


r 


165 


♦ 


97 


* 


120 


143 


a 


166 


m 


96 


a 


121 


^X 144 


1 


167 


H 


99 


f^ 


122 


Q 145 


u 


168 


(- 


100 


+ 


123 


A 146 


B 


169 




101 


c 


124 


fP 147 


LI 


170 


— 


102 


m 


125 


Q 148 


[B 


171 


D 


103 


Tr 


126 


Brown 149 


172 


a 


104 


a 


127 


LtRed 150 


h 
U 
H 


173 


5! 


105 




128 


Dk. Gray 151 


174 


n; 


106 


Orange 129 


Gray i52 


175 


T 


107 




130 


Lt. Green 153 


176 


D 


108 




131 


Lt. Blue 154 


-H 


177 


N 


109 




132 


Lt. Gray 155 


fr 


178 


v\ 


110 


(1 


133 


lA 156 


a] 


179 


n 


111 


f3 


134 


Q 157 


r 


180 


n 


112 


f5 


135 


WSk. 158 


c 


181 


m 


113 


f7 


136 


^^^ 159 


a 


182 


u 


114 


f2 


137 


Q^J 160 


r 


183 



CODES 


192-223 


SAME AS 


96-127 


CODES 


224-254 


SAME AS 


160-190 


CODE 


255 


SAME AS 


126 



PRINTS 


CHRS 


PRINTS 


CHRS 


PRINTS 


CHRI 


PRRITS 


CHW 


n 


184 

185 


u 


186 
187 


J 


188 
189 


E 
H 


190 

191 
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NOTE: The 80-column (RGBI) output has three colors that are different 
from the 40-column (composite video) color output. This means that the 
character string codes that represent color codes for these three colors are 
used differently depending on which video output is used. The following 
character string codes represent these colors in each video output. 



u 



u 



CHR$ 



40-COLUMN (VIC COMPOSITE) 



129 


Orange 


149 


Brown 


151 


Dark Gray 



80-COLUMN (8563 RGBI) 

Dark Purple 
Dark Yellow 
Dark Cyan 



u 



u 



u 



u 
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SCREEN AND COLOR MEMORY MAPS— 
CI 28 MODE, 40-COLUMN 
AND C64 MODE 

The maps below display the memory locations used in 40-column mode (C128 and C64) 
for identifying the characters on the screen as well as their color. Each map is separately 
controlled and consists of 1000 positions. 

The character displayed on the maps can be controlled directly with the POKE 
command. 



VIC CHIP (40-COLUMN) SCREEN MEMORY MAP 



COLUMN 
20 



55296- 

55336 

55376 

55416 

55456 

55496 

55536 

55576 

55616 

55656 

55696 

55736 

55776 

55816 

55856 

55896 

55936 

55976 

56016 

56056 

56096 

56136 

56176 

56216 

56256 



rill- -\- 






„ :i_[ i ]_j"j -"~-~^ 




i i 


,. i....^. 1 ,.4. ., . , , ._! _ 


._ J 1 t 


__±_y^ +"^ ^-^^^ -p J — 












- 1 ! M ' ' 


TV T"±- : :it:±t U IIL^ i 


-j- -J- __v ..,_^ 1 




1 1 1 . 1 ' ' 


'■ 













39 

55335 
J 





-| 10 



f 
56295 



n 



The Screen Map is POKEd with a Screen Display Code value (see Appendix D). 
For example: 

POKE 1024, 13 (from BANK or 15) 

will display the letter M in the upper-left comer of the screen. 



n 
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VIC CHIP (40-COLUMN) COLOR MEMORY MAP 



COLUMN 

20 



1024- 

1064 

1104 

1144 

1184 

1224 

1264 

1304 

1344 

1384 

1424 

1464 

1504 

1544 

1584 

1624 

1664 

1704 

1744 

1784 

1824 

1864 

1904 

1944 

1984 



1063 
\ 






i 

u 

U 
U 



10 I 



t 

2023 



If the color map is POKEd with a color value, this changes the character color. For 
example: 

POKE 55296,1 (from BANK 15) 

will change the letter M inserted above from light green to white. 



r 

u 

u 



COLOR CODES— 40 COLUMNS 


Black 


8 Orange 


1 White 


9 Brown 


2 Red 


10 Light Red 


3 Cyan 


11 Dark Gray 


4 Purple 


12 Medium Gray 


5 Green 


13 Light Green 


6 Blue 


14 Light Blue 


7 Yellow 


15 Light Gray 


Border Control Memory 53280 


Background Control Memory 53281 



u 



u 
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APPENDIX G 



DERIVED TRIGONOMETRIC 
FUNCTIONS 



n 



n 

n 



FUNCTION 

SECANT 
COSECANT 
COTANGENT 
INVERSE SINE 
INVERSE COSINE 

INVERSE SECANT 
INVERSE COSECANT 

INVERSE COTANGENT 
HYPERBOLIC SINE 
HYPERBOLIC COSINE 
HYPERBOLIC TANGENT 

HYPERBOLIC SECANT 
HYPERBOLIC COSECANT 
HYPERBOLIC COTANGENT 

INVERSE HYPERBOLIC SINE 
INVERSE HYPERBOLIC COSINE 
INVERSE HYPERBOLIC TANGENT 
INVERSE HYPERBOLIC SECANT 

INVERSE HYPERBOLIC COSECANT 

INVERSE HYPERBOLIC COTANGENT 



BASIC EQUIVALENT 

SEC(X) = l/COS(X) 

CSC(X) = 1/SIN(X) 

C0T(X) = 1/TAN(X) 

ARCSIN(X) = ATN(X/SQR(-X*X + 1)) 

ARCCOS(X) =-ATN(X/SQR 

(-X*X. +1)) +1I/2 

ARCSEC(X) = ATN(X/SQR(X*X-1)) 

ARCCSC(X) = ATN(X/SQR(X*X-1)) 

+ (SGN(X)-1)*W2 
ARCCOT(X) = -ATN(X) + ir/2 
SINH(X) = (EXP(X)-EXP(-X))/2 
COSH(X) = (EXP(X) + EXP(-X))/2 
TANH(X) = -EXP(-X)/(EXP(X) + EXP 

(-X))*2+l 
SECH(X) = 2/(EXP(X) + EXP(-X)) 
CSCH(X) = 2/(EXP(X)-EXP(-X)) 
COTH(X) = EXP(-X)/(EXP(X) 

-EXP(-X))*2 + 1 
ARCSINH(X) = LOG(X + SQR(X*X + 1)) 
ARCCOSH(X) = LOG(X + SQR(X*X-1)) 
ARCTANH(X) = LOG(l + X)/(l-X))/2 
ARCSECH(X) = LOG(SQR 

(-X*X + 1) + 1/X) 
ARCCSCH(X) = LOG(SGN(X)*SQR 

(X*X + 1)/X) 
ARCCOTH(X) = LOG((X + l)/(x-l))/2 



n 



n 
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CONTROL AND ESCAPE CODES 

CONTROL CODES 

The table below lists the control codes used by the Commodore 128. The print codes 
in the first column are used in PRINT statements. The key codes in the second 
column are the sequence of keys pressed to perform specific controls. Hold down 
the CONTROL key (or the key specified on the left in the key code column) 
and strike the key specified to the right in the key code column. 



PRINT 












CODES 


KEY CODES 
















EFFECTIVE 










IN MODE: 


(CHR$) 


KEY SEQUENCE 


FUNCTION 


C64 


C128 


CHR$(2) 


CTRLB 




Underline (80) 




y 


CHR$(5) 


CTRL 2 or 


CIRL E 


Set character color to white 


y 


y 


CHR$(7) 


CTRLG 




Produce bell tone 




y 


CHR$(8) 


CIKL H 




Disable character set change 


y 




CHR$(9) 


CTRL I 




Enable character set change 
Move cursor to next set tab 
position 


y 


y 


CHR$(10) 


CTRL J 




Line feed 




y 


CHR$(11) 


CTRLK 




Enable character set change 




y 


CHR$(12) 


CTRLL 




Disable character mode change 




y 


CHR$(13) 


CTRLM 




Send a carriage return and line 
feed to the computer and enter a 












Itaie of BASIC 


y 


y 


CHR$(14) 


CTRLN 




Set character set to upper/lower 












case 


y 


y 


CHR$(15) 


CIRL O 




Turn flash on (80) 




y 


CHR$(17) 


CRSR DOWN/CTRL 


Move the cursor down one 








Q 




row 


y 


y 


CHR$(18) 


CTRL 9 or 


CTRLR 


Cause characters to be printed hi 












reverse field 


y 


y 



CHR$(19) HOME 



Move the cursor to the home po- 
sition (top left) of the display (the 
current window) 



y y 



u 
u 
u 

u 

I 

L 

u 

u 
u 
\1 



NOTE: (40) = 40-column screen only. 
(80) = 80-column screen only. 
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PRINT 










CODES 


KEY CODES 














EFFECTIVE 








IN MODE: 


(CHR$) 


KEY SEQUENCE 


FUNCTION 


C64 


C128 


CHR$(20) 


DEL or CTRL T 


Delete last character typed and 
move all characters to the right 
of the deleted character one space 










to the left 


y 


y 


CHR$(24) 


CTRL X, C IRL TAB 
or & TAB 


Tab set/clear 






CHR$(27) 


ESC or CTRL[ 


Send an ESC character 




y 


CHR$(28) 


CTRL 3 or C'lRL £ 


Set character color to red (40) 










and (80) 


y 


y 


CHR$(29) 


CRSR or CTRL] 


Move cursor one column to the 










right 


y 


y 


CHR$(30) 


CTRL 6 or CTRL 


Set character color to green (40) 










and (80) 


y 


y 


CHR$(31) 


CTRL 7 or Ci'RL = 


Set character color to blue (40) 
and (80) 






CHR$(34) 




Print a double quote on screen 










and place editor in quote mode 


y 


y 


CHR$(129) 


Ol 


Set character color to orange (40); 










darl( purple (80) 


y 


y 


CHR$(130) 




Underline off (80) 




y 


CHR$(131) 




Run a program. This CHR$ code 
does not work in PRINT CHR$ 
(131), but works from keyboard 










buffer 


y 


y 


CHR$(133) 


Fl 


Reserved CHR$ code for Fl key 


y 


y 


CHR$(134) 


F3 


Reserved CHR$ code for F3 key 


y 


y 


CHR$(135) 


F5 


Reserved CHR$ code for F5 key 


y 


y 


CHR$(136) 


F7 


Reserved CHR$ code for F7 key 


y 


y 


CHR$(137) 


F2 


Reserved CHR$ code for F2 key 


y 


y 


CHR$(138) 


F4 


Reserved CHR$ code for F4 key 


y 


y 


CHR$(139) 


F6 


Reserved CHR$ code for F6 key 


y 


y 


CHR$(140) 


F8 


Reserved CHR$ code for F8 key 


y 


y 


CHR$(141) 


SHIFT RETURN, 
CTRL ENTER, 
O ENTER or 


Send a carriage return and line 
feed without entering a BASIC 








O RETURN 


line 


y 


y 


CHR$(142) 




Set the character set to upper 










case/graphic 


y 


y 


CHR$(143) 




Turn flash off (80) 




y 



NOTE: (40) = 40-column screen only. 
(80) = 80-column screen only. 
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PRINT 
CODES 


KEY CODES 


(CHR$) 


KEY SEQUENCE 


CHR$(144) 


CTRLl 


CHR$(145) 


CRSRUP 


CHR$(146) 
CHR$(147) 


CTRLO 
CLEAR HOME 



CHR$(148) INST 



CHR$(149) 


O 


2 


CHR$(150) 


O 


3 


CHR$(151) 


O 


4 


CHR$(152) 


O 


5 


CHR$(153) 


Cf 


6 


CHR$(154) 


O 


7 


CHR$(155) 


O 


8 


CHR$(156) 


CTRL 5 


CHR$(157) 
CHR$(158) 


CRSR LEFT 
CTRL 8 


CHR$(159) 


or( 


CTRL 4 





EFFECTIVE 




IN MODE: 


FUNCTION 


C64 


C128 


Set character color to black (40) 






and (80) 


y 


y 


Move cursor or printing position 






up one row 


/ 


y 


Terminate reverse field display 


y 


y 


Clear the window screen and 






move the cursor to the top-left 






position 


y 


y 


Move character from cursor 






position end of line right one 






column 


y 


y 


Set character color to brown (40); 






dark yeUow (80) 


y 


y 


Set character color to light red 






(40) and (80) 


y 


y 


Set character color to dark gray 






(40); dark cyan (80) 


y 


y 


Set character color to medium 






gray (40) and (80) 


y 


y 


Set character color to light green 






(40) and (80) 


y 


y 


Set character color to light blue 






(40) and (80) 


y 


y 


Set character color to light gray 






(40) and (80) 


y 


y 


Set character color to purple (40) 






and (80) 


y 


y 


Move cursor left by one column 


y 


y 


Set character color to yellow (40) 






and (80) 






Set character color to cyan (40); 






light cyan (80) 


y 


y 



u 
u 

I I 

u 
Q 



U 

U 
U 



NOTE: (40) = 40-column screen only. 
(80) = 80-coluran screen only. 






n 
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ESCAPE CODES 

This table lists the key sequences for the ESCape functions available on the Commodore 
128. ESCape sequences are entered by pressing and releasing the ESC key, fol- 
lowed by pressing the key listed in the right column. 



ESCAPE FUNCnON 

Cancel quote, reverse, flash 

Erase to end of current line 
Erase to start of current line 
Clear to end of screen 



-1 


Move to start of current line 
Move to end of current line 


n 


Enable auto-insert mode 
Disable auto-insert mode 


\ 


Delete current line 
Insert line 


n 


Set default tab stop (8 spaces) 
Clear all tab stops 


"^ 


Enable scrolling 
Disable scrolling 




Scroll up 
Scroll down 



SEQUENCE KEY 


ESCO 


ESCQ 
ESCP 

ESC@ 


ESC J 
ESCK 


ESC A 
ESCC 


ESCD 
ESC I 


ESCY 
ESCZ 



Enable bell (by control-G) 
Disable bell 

Set cursor to nonflashing mode 
Set cursor to flasliing mode 

Set bottom right comer of screen window at cursor position 
Set top left corner of screen window at cursor position 



ESCL 
ESCM 

ESCV 
ESCW 

ESCG 
ESCH 

ESCE 
ESCF 

ESCB 
ESCT 

ESCX 



Swap 40/80 column display output device 

The following ESCape sequences have an effect on an 80-column screen only. 



ESCAPE FUNCTION 

Change to underlined cursor (80) 
Change to block cursor (80) 

Set screen to reverse video (80) 

Return screen to normal (non reverse video) state (80) 



SEQUENCE KEY 

ESCU 
ESCS 

ESCR 

ESCN 
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BASIC 7.0 ABBREVIATIONS 

NOTE: The abbreviations below operate in upper case/graphics mode. Press the letter 
key(s) indicated, then hold down the SHIFT key and press the letter key follow- 
ing the word SHIFT. 



KEYWORD 

ABS 

APPEND 

ASC 

ATN 

AUTO 

BACKUP 

BANK 

BEGIN 

BEND 

BLOAD 

BOOT 

BOX 

BSAVE 

BUMP 

CATALOG 

CHAR 

CHR$ 

CIRCLE 

CLOSE 

CLR 

CMD 

COLLECT 

COLLISION 

COLOR 

CONCAT 

CONT 

COPY 

COS 

DATA 

DEC 

DCLEAR 

DCLOSE 

DEFFN 

DELETE 

DIM 



ABBREVIATION 

A SHIFT B 
A SHIFT P 
A SHIFT S 
A SHIFT T 
A SHIFT U 
BA SHIFT C 
B SHIFT A 
B SHIFT E 
BE SHIFT N 
B SHIFT L 
B SHIFT O 

none 
B SHIFTS 
B SHIFT U 
C SHIFT A 
CH SHIFT A 
C SHIFT H 
C SHIFT I 
CL SHIFT O 
C SHIFT L 
C SHIFT M 
COLL SHIFT E 
COL SHIFT L 
COL SHIFT O 
C SHIFT O 
none 
CO SHIFT P 
none 
D SHIFT A 
none 
DCL SHIFT E 
D SHIFT C 
none 
DE SHIFT L 
D SHIFT I 



Q 



U 






U 



n 
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KEYWORD 

DIRECTORY 

DLOAD 

DO 

DOPEN 

DRAW 

DS 

DS$ 

DSAVE 

DVERIFY 

EL 

END 

ENVELOPE 

ER 

ERR$ 

EXIT 

EXP 

FAST 

FETCH 

FILTER 

FOR 

FRE 

FNXX 

GET 

GETKEY 

GET# 

GOSUB 

G064 

GOTO 

GRAPfflC 

GSHAPE 

HEADER 

HELP 

HEX$ 

IF . . . GOTO 

IF . , . THEN . 

INPUT 

INPUT# 

INSTR 

INT 

JOY 

KEY 

LEFTS 

LEN 

LET 

LIST 

LOAD 

LOCATE 

LOG 



ELSE 



ABBREVIATION 


DI SHIFT R 


D SHIFT L 


none 


D SHIFT O 


D SHIFT R 


none 


none 


D SHUl' S 


D SHIFTY 


none 


none 


E SHIFT N 


none 


E SHIFT R 


EX SHIFT I 


E SHIFT X 


none 


F SHIFT E 


F SHIFT I 


F SHIFT O 


F SHIFT R 


none 


G SHIFT E 


GETK SHIFT E 


none 


GO SHin S 


none 


G SHUl 


G SHIFT R 


G SHIFI S 


HE SHU T A 


X SHIFT X 


H SHIFT E 


none 


none 


none 


I SHIFT N 


IN SHIFT S 


none 


J SHUT O 


K SHIFT E 


LE SHIFT F 


none 


L SHU r E 


L SHIFT I 


L SHIFT O 


LO SHIFT C 


none 
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KEYWORD 

LOOP 

MID$ 

MONITOR 

MOVSPR 

NEW 

NEXT 

ON GOSUB 

ON GOTO 

OPEN 

PAINT 

PEEK 

PEN 

PI 

PLAY 

POINTER 

POKE 

POS 

POT 

PRINT 

PRINT# 

PRINT USING 

PUDEF 

RCLR 

RDOT 

READ 

RECORD 

REM 

RENAME 

RENUMBER 

RESTORE 

RESUME 

RETURN 

RGR 

RIGHTS 

RND 

RREG 

RSPCOLOR 

RSPPOS 

RSPR 

RSPRTTE 

RUN 

RWINDOW 

SAVE 

SCALE 

SCNCLR 

SCRATCH 

SGN 



ABBREVIATION 


LO SHIFT 


M SHIFT I 


MO SHIFT N 


M SHU' 1' 


none 


N SHIFT E 


ON GO SHIFT S 


ON G SHIFT 


SHU 1 P 


P SHIFT A 


PE SHIFT E 


P SHIFT E 


none 


P SHIFT L 


PO SHIFT I 


PO SHIFT K 


none 


P SHIFT 


none 


P SHIFT R 


US SHIFT I 


P SHU 1 U 


R SHIFT C 


R SHU r D 


RE SHUT A 


R SHIFT E 


none 


RE SHI hi N 


REN SHIFT U 


RE SHIFTS 


RFS SHIFT U 


RE SHIFT T 


R SHIFT G 


R SHU 1 I 


R SHUT N 


R SHUT R 


RSP SHIFT C 


R SHIFTS 


none 


RSP SHIFT R 


R SHUT U 


R SHUT W 


S SHIFT A 


SC SHIFT A 


S SHIFT C 


SC SHIFT R 


S SHIFT G 



u 

Q 



U 







u 



U 
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KEYWORD 

SIN 

SLEEP 

SLOW 

SOUND 

SPC 

SPRCOLOR 

SPRDEF 

SPRITE 

SPRSAV 

SQR 

SSHAPE 

STASH 

ST 

STEP 

STOP 

STR$ 

SWAP 

SYS 

TAB( 

TAN 

TEMPO 

TI 

TI$ 

TO 

TRAP 

TROFF 

TRON 

UNTIL 

USR 

VAL 

VERIFY 

VOL 

WAIT 

WHILE 

WIDTH 

WINDOW 

XOR 



ABBREVIATION 


SSHini 


S SHIFT L 


none 


S SHIFT O 


none 


SPR SHIFT C 


SPR SHIFT D 


S SHIFT P 


SPR SHIFT S 


S SHIFT Q 


S SHIFTS 


S SHIFT T 


none 


ST SHIFT E 


ST SHIFl O 


ST SHHT R 


S SHIFT W 


none 


T SHIFT A 


none 


T SHIFT E 


none 


none 


none 


T SHUT R 


TRO SHIFT F 


TR SHIFT 


U SHIFT N 


U SHIFTS 


none 


V SHIFT E 


V SHIFT 


W SHIFT A 


W SHIFT H 


WI SHIFT D 


W SHUT I 


X SHIFT 
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DISK COMMAND SUMMARY 



This appendix lists the commands used for disk operation in C128 and C64 modes 
on the Commodore 128. For detailed information on any of these commands, see 
Chapter 2. Your disk drive manual also has information on disk commands. 

The new BASIC 7.0 commands can be used only in C128 mode. All BASIC 2.0 
commands can be used in both CI 28 and C64 modes. 



u 



COMMAND 


USE 


BASIC 2.0 


BASIC 7.0 


APPEND 


Append data to file 




y 


BLOAD 


Load a binary file starting at the specified 
memory location 




y 


BOOT 


Load and execute a bootable program 




y 


BSAVE 


Save a binary file from the specified mem- 
ory location 




y 


CATALOG 


Display directory contents oS dMa <m screen* 




y 


CLOSE 


Close logical disk file 


y 




CMD 


Redirect screen output to a peripheral 
device 


/ 




COLLECT 


Free inaccessible disk space"* 




y 


CONCAT 


Concatenate two data files* 




y 


COPY 


Copy files between devices* 




y 


DCLEAR 


Clear all open channels on disk drives 




y 


DCLOSE 


Close logical disk file 




y 


DIRECTORY 


Display directory of contents of disk on 
screen* 




y 


DLOAD 


Load a BASIC program ttom disk 




y 


DOPEN 


Open a disk file for a read and/or write 
operation 




y 


DSAVE 


Save a BASIC program to disk 




y 


DVERUY 


Verify program in memory agahist pro- 
gram on disk 




y 


GET# 


Receive input from open disk file 


/ 




HEADER 


Format a disk* 




y 


LOAD 


Load a file from disk 


/ 




OPEN 


Open a file for input or output 


y 




PRINT# 


Output a data to file 


y 




RECORD 


Position relative file pointers* 




y 


RENAME 


Change name of a file on disk* 




y 



u 

u 







y 



( I 



/ I 



COMMAND 

RUN filename 

SAVE 

VERIFY 



USE 
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BASIC 2.0 BASIC 7.0 



Execute BASIC program from disk 
Store program in memory to disk / 

Verify program in memory against pro- / 

gram on disk 



/ 



♦Although there is no single equivalent command in BASIC 2.0, there is an equivalent multi-command 
instruction. See your disk drive manual for these BASIC 2.0 conventions. 



n 
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A 


(Accumulator) 


BC 




DE 




HL 




PSW 


(Status Word) 


IX 


(X register) 


lY 


(Y index register) 


PC 


(program counter)' 


SP 


(stack pointer) 



Certain registers can be used as a register pair, to represent a 16 bit address, or as 
single 8-bit register. The Z80 has a duplicate set of registers for interrupt processing. 

For more detailed information on the Z80 microprocessor consult the "Sugges- 
tions for Further Reading." For more detailed information on the CP/M system, refer to 
the Commodore 128 System Guide to receive the full set of CP/M Plus documentation, 
written by Digital Research Inc., through Commodore. 



U 




K^ 



c-i 



PART I— COMMODORE 128 CP/M 

This appendix explains each CP/M BIOS, 8502 BIOS and User Function routine and 
how to call each in Z80 assembly language. This section assumes you akeady have 
some knowledge about Z80 machine language and the basic operations of the CP/M 
system. If you need more information about Z80 or CP/M, your local bookstore 
probably has several good reference books about these widely covered subjects. To fully 
cover these topics is beyond the scope of this reference guide. See "Suggestions for 
Reading" at the end of this guide. I 1 

Part I of this appendix first lists each CP/M BIOS, 8502 BIOS and User Function '-' 

routine by number. Part II explains how and provides examples to call these routines. 
Part III lists the Z80 memory map. | ! 

The format used to describe these routines are as follows: U 

a) Function Name i "j 

b) Input Parameters ) ! 

c) Output Parameters 

d) Brief Description 

e) Other required preparatory/post routines (or additional information) | j 

The 8502 BIOS and User Function routines require certain values to be placed into 
the Z80 microprocessor registers. In Chapter 5 you learned about the 8502 microproces- , | 

sor registers: A, X, Y, Status (PSW), Stack Pointer (S) and Program Counter (PC). The |j 

Z80 also has applicable registers. The Z80 registers are named as follows: 





u 
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COMMODORE 128 CP/M BIOS ROUTINES 



n 



The Commodore 128 CP/M system has a set of routines called the CP/M BIOS, which 
handle the low level input/output operations of the system. Each of these routines can 
be accessed via the CP/M BIOS jump table below. The jump vector numbers through 
29 are the CP/M BIOS jump vectors. The 30th jump vector is for system dependent 
User Functions. These are discussed following the CP/M BIOS routines. 

The 8502 BIOS routines are a subset of the system dependent User Functions 
(specifically. User Function 4) contained in the Commodore 128 CP/M system. Many of 
the User Functions have subfunctions which require certain parameters to be passed 
through the Z80 registers. This is discussed in detail in the User Function section in this 
appendix. Examples of calling the CP/M BIOS and User Function routines are provided 
in Part II of this appendix. 



n 



NO. INSTRUCTION 



DESCRIPTION 



1 I 





JMPBOOT 




1 


JMP WBOOT 




2 


JMP CONST 


r*i 


3 


JMP CONIN 


j 


4 


JMP CONOUT 




5 


JMP LIST 




6 


JMP AUXOUT 


n 


7 


JMP AUXIN 


1 ! 


8 


JMP HOME 




9 


JMP SELDSK 




10 


JMP SETTRK 


r~i 


11 


JMP SETSEC 


1 


12 


JMP SETDMA 




13 


JMP READ 




14 


JMP WRITE 


r» 


15 


JMP LISTST 


t 
1 1 


16 


JMP SECTRN 


( 1 


17 


JMP CONOST 




18 


JMP AUXIST 


f-^ 


19 


JMP AUXOST 


1 


20 


JMP DEVTBL 


\ 


21 


JMPDEVINI 




22 


JMP DRVTBL 


r-^ 


23 


JMP MULTIO 


1 1 


24 


JMP FLUSH 


) 1 


25 


JMP MOVE 




26 


JMP TIME 


pn 


27 


JMP SELMEN 


1 > 


28 


JMP SETBNK 


/ I 


29 


JMP XMOVE 




30 


JMP USERF 


f-^ 


31 


JMP RESERVl 


) 


32 


JMP RESERV2 



Perform cold start initialization 

Perform warm start initialization 

Check for console input character ready 

Read Console Character in 

Write Console Character out 

Write List Character out 

Write Auxiliary Output Character 

Read Auxiliary Input Character 

Move to Track 00 on Selected Disk 

Select Disk Drive 

Set Track Number 

Set Sector Number 

Set DMA Address 

Read Specified Sector 

Write Specified Sector 

Return List Status 

Translate Logical to Physical Sector 

Return Output Status of Console 

Return Input Status of Aux. Port 

Return Output Status of Aux. Port 

Return Address of Char. I/O Table 

Initialize Char. I/O Devices 

Return Address of Disk Drive Table 

Set Number of Logteally Comecutive sectors to be read or written 

Force Physical Buffer Flushing for user-supported deblocking 

Memory to Memory Move 

Time Set/Get signal 

Select Bank of Memory 

Specify Bank for DMA Operation 

Set Bank When a Buffer is in a Bank other than or 1 

Reserved for System Implementor 

Reserved for Future Use 

Reserved for Future Use 



CP/M 3 BIOS Jump Vector Table 
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BOOT 






Bank: 







Input: 


None 




Output: 


None 




Function: 


This code does all of the hardware initialization, sets up zero 
page, prints any sign-on message and loads the CCP and then 
transfers control to the CCP. 


1 


WBOOT 






Bank: 


Oor 1 




Input: 


None 




Output: 


None 




Function: 


This code sets up page zero, reloads the CCP and then exe- 
cutes the CCP. 


2 


CONST 






Bank: 


Oorl 




Input: 


None 




Output: 


A=OFFH if console character 



Function: 



3 CONIN 
Bank: 
Input: 
Output: 
Function: 



CONOUT 
Bank: 
Input: 
Output: 
Function: 



5 LIST 
Bank: 
Input: 
Output: 
Function: 



A=OOH if no console character 

Checks the console input status of the current console devices. 
If any of the devices have a character available, FFH is 
returned, otherwise OOH is returned. 

Oorl 

None 

A = ASCII console character 

Reads a character from any ONE of the assigned console input 

devices. A scan of each assigned device is done until an 

input character is found. The character is returned in the A 

register. 

Oorl 

C = ASCII character to display 

None 

Sends the character in C to ALL devices that are currently 

assigned to the console. It waits for all assigned devices to 

accept a character before exiting. 

Oorl 

C= ASCII character to print 

None 

Sends the character in C to ALL devices that are currently 

assigned to the LIST device. It waits for all assigned devices 

to accept a character before exiting. 



u 



u 



IvJ 



U 



U 


u 
y 

w 

u 
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AUXOUT 
Bank: 
Input: 
Output: 
Function: 



7 AUXIN 
Bank: 
Input: 
Output: 
Function: 



8 HOME 
Bank: 
Input: 
Output: 
Function: 



9 SELDSK 
Bank: 
Input: 

Output: 

Function: 



10 SETTRK 

Bank: 
Input: 
Output: 
Function: 



11 



SETSEC 
Bank: 
Input: 
Output: 
Function: 



Oorl 

C = ASCII Character to send to AUX device 

None 

Sends the character in C to ALL devices that are currently 

assigned to the AUXOUT device. It waits for all assigned devices 

to accept a character before exiting. 

Oor 1 

None 

A = ASCII character from AUX device 

Reads a character from any ONE of the assigned AUXIN devices. 

A scan of each assigned device is done until an input character 

is found. The character is returned in the A register. 



None 

None 

Homes the head on the currently selected disk drive. This 

function sets the current track to and does not move the head 

of the disk. 



C = Disk Drive (0-15) (A = 0) 

E= Initial Select Flag (LSB) 

HL= Address of Disk Parameter Header (DPH) if drive exists. 

HL = OOOH if drive does not exist. 

Selects the disk drive whose address is in C as the current drive 

for all further disk operations. If the LSB of the E register is a 

zero, then this is the first logging of this disk. The disk type 

(C64 CP/M, MFM or C128 CP/M) is checked and the DPB 

parameters adjusted for the diskette currently in the drive. 



BC = Track number 

None 

Register pair BC contains the track number to be used in the 

subsequent disk access. This value is saved. 



BC = Sector number 

None 

Register pair BC contains the sector number to be used in the 

subsequent disk access. This value is saved. The value in BC 

is the value returned by the sector translation routine (in HL). 
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12 SETDMA 
Bank: 
Input: 
Output: 
Function: 



13 READ 
Bank: 
Input: 
Output: 



Function: 



14 WRITE 
Bank: 
Input: 
Output: 



Function: 



15 LISTST 
Bank: 
Input: 
Output: 

Function: 





BC = Direct memory access address 

None 

The value in BC is saved as the current DMA address. This is 

the address where ALL disk reads or writes occur. The DMA 

address that is set is used until it is changed by a future call to 

this routine to change it. 



None 

A = OOOH if no errors 

A=001H if nonrecoverable error 

A=OFFH if media has changed 

Reads the sector addressed by the current disk, track and 

sector to the current DMA address. If the data is read with no 

errors then A=0 on return. If an error occurs, the operation is 

tried several more times, and if a successful read does not 

occur then A is set to OOIH. A test for media change is 

performed each time this routine is called and A is set to -1 if 

the media has been changed. 



C = Deblocking code (not used) 

A = OOOH if no errors 

A = OOIH if nonrecoverable error 

A=002H if disk is read only 

A=OFFH if media has changed 

Writes the sector addressed by the current disk track and 

sector from the current DMA address. If the data is written with 

no errors, then A is set to on return. If an error occurs, the 

operation is tried several more times, and if a successful write 

does not occur, then A is set to OOIH. A test for media change 

is performed each time this routine is called and A is set to 

-1 if the media has been changed. Also, if an attempt is made 

to write to a read-only disk, then the A register is set to 002H. 

Oor 1 

None 

A = OOH if list device is not ready to accept a character. 

A = OFFH if list device is ready to accept a character. 

This routine scans the currently assigned list devices and returns 

with A set to OFFH if ALL assigned devices are ready to accept a 

character. If any assigned device is not ready then A is set 

to OOH. 
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17 



18 



19 



20 



SECTRN 
Bank: 
Input: 

Output: 
Function: 



CONOST 
Bank: 
Input: 
Output: 

Function: 



AUXIST 
Bank: 
Input: 
Output: 

Function: 



AUXOST 
Bank: 
Input: 
Output: 

Function: 



DEVTBL 
Bank: 
Input: 
Output: 
Function: 





BC = Logical sector number (0-n) 

DE= Translation table address (from DPB) 

HL = Physical sector number 

This routine converts the physical sector number to a logical 

sector number. If no translation is needed then it moves the 

BC register to HL and returns. 

Oorl 

None 

A = OFFH if Ready 

A = OOOHifnotReady 

This routine scans the currently assigned console devices and 

returns with A set to OFFH if ALL assigned devices are ready 

to accept a character. If any assigned device is not ready then 

A is set to OOOH. 

Oorl 

None 

A = OFFH if console character present 

A = OOOH if no console character 

Checks the status of the current AUXIN device. If any of the 

devices have a character available, OFFH is returned, oflierwise 

OOOH is returned. 

Oorl 

None 

A = OFFH if ready 

A = OOOH if not ready 

This routine scans the currently assigned AUXOUT devices and 

returns with A set to OFFH if ALL devices are ready to accept a 

character. If any assigned device is not ready then A is set 

toOOH. 

Oorl 

None 

HL = address of character I/O table 

This routine returns the address of the Character I/O table. 

This table is used to name each of the driver modules and 

set/control the baud rate and XON/XOFF logic for each driver. 

Note: the device drive mechanism is used to replace the lOBYTE 

used with CP/M 2.2. 



682 COMMODORE 128 



u 



21 
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DEVINI 
Bank: 
Input: 
Output: 
Function: 

DRVTBL 
Bank: 
Input: 
Output: 
Function: 



u 



23 MULTIO 
Bank: 
Input: 
Output: 
Function: 



24 FLUSH 
Bank: 
Input: 
Output: 



Function: 

25 MOVE 
Bank: 
Input: 



Output: 
Function: 



26 TIME 
Bank: 
Input: 
Output: 



Oor 1 

C = device number 

None 

Initializes the physical character device specified in the C 

register to the BAUD rate in the DEVTBL. 



None 

HL = address of the drive table 

Returns the address of the drive table in HL (NOTE: first 

instruction MUST be LXI H, DRVTBL). The drive table is a 

list of 16 word pointers that point to the DPH for that drive. If 

a drive is not present in the system, then the pointer for that 

drive is set to zero. 



C = multisector count 

None 

The multisector count is set before the track, sector, and DMA 

address and the read/write of the sectors occur. A maximum 

of 16K can be transferred by each multisector count. 



None 

A=OOOH if no errors 

A=001H if nonrecoverable error 

A = 002H if disk is read-only 

A = OFFH if media has changed 

This routine is used only if blocking/deblocking is done in the 

BIOS. This code ALWAYS returns with A =000H. 

Oorl 

HL= destination address 

DE = source address 

BC = count 

HL = HL(in) + BC(in) 

DE=DE(in)-l-BC(in) 

Moves a block of data. Data to be moved is to/from the current 

memory bank (or common) unless the XMOVE routine is 

called first, then the move is an interbank data movement. 

Oorl 

C = OOOH (Time Get) / OFFH (Set Time) 

None 



IJ 
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27 



Function: 



SELMEM 
Bank: 
Input: 
Output: 
Function: 



This function is called with C=OOOH if the system time in the 
SCB needs to be updated by the clock. If C = OFFH, then the 
time in the SCB has just been updated and the clock is 
set to the SCB time. NOTE: HL and DE MUST be preserved. 



Oor 1 

A = memory bank 

None 

Changes the current memory bank. 

common memory. 



This code MUST be in 



NOTE: ONLY A can be changed. 



28 SETBNK 

Bank: 
Input: 
Output: 
Function: 

29 XMOVE 

Bank: 
Input: 

Output: 
Function: 

30 USERF 

Banks 
Input: 
Output: 
Function: 



31 



32 



RESERVl 
Bank: 
Input: 
Output: 
Function: 

RESERV2 
Bank: 
Input: 
Output: 
Function: 





A=DMA memory bank 

None 

Sets the DMA bank for the next READAVRTTE operation. 



B = destination bank 
C = source bank 
None 

Provides the system with the ability to perform memory-to- 
memory DMA through the entire system space. 

Oor 1 

A = function number, L = subfunction number 

Outputs depend on the called function or subfunction. 

This calls the user functions and 8502 BIOS routines, which 

are defined in the Commodore 128 System Dependent User 

Function section. 

N/A 
N/A 
N/A 
Not available to the user. 

N/A 
N/A 
N/A 
Not available to the user. 
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DATA STRUCTURES 

SYSTEM CONTROL BLOCK— (SCB) 

The System Control Block is a 100-byte data structure. The data structure is 
used as the basic communication between the various modules that make up the 
CP/M Plus system. The contents of the data structure are system parameters and 
variables. 



DRIVE TABLE (DRVTBL) 



U 
U 

y 



\ ! 



PHO through DPMI 5 

A list of 16 word pointers (reverse-byte format). The first pointer (DPHO) is 
drive A and the last pointer (DPH15) is drive P. The pointers point to the XDPH 
for that disk drive. Any drive that is not in the system has its pointers set to 
zero. 

EXTENDED DISK PARAMETER HEADER (XDPH) 
(NORMAL DPH WITH A HEADER) 



WRT READ LOGIN INTT TYPE UNIT XLT 


-0- 


MF 


DPB CSV ALV DIRBCB DTABCB HASH HBANK 


16b 16b 


16b 


16b 8b 


8b 


16b 72b 


8b 


16b 16b 16b 


16b 


16b 


16b 


8b 


-10 -8 


-6 


-4 -2 


-1 





2 


11 


12 14 16 


18 


20 


22 


24 



WRT Contains the address of the sector write routine for this drive. 

READ Contains the address of the sector read routine for this drive. 

LOGIN Contains the address of the login routine for this drive. 

INIT Contains the address of the first time initialization routine for this drive. 

TYPE This byte is used by the BIOS to keep track of density and media type. 

UNIT Contains the drive number relative to the disk controller. 

XLT Contains the address of the sector translation table or zero if none. 

-0- BDOS scratch area (9 bytes). 

MF Media flag cleared to zero if disk logged in. BIOS sets to OFFH if media 

has changed. 

DPB Contains a pointer to the current DPB that describes the current media type. 

CSV Contains a pointer to directory checksum area (one per disk drive). 

ALV Contains a pointer to allocation vector area (one per disk drive). 

DIRBCB Contains a pointer to a single directory Buffer Control Block (BCB). 

DTSBCB Contains a pointer to a single data Buffer Control Block (BCB). 

HASH Contains a pointer to an optional directory hashing table (FFFFH is 

not used). 

HBANK Contains a bank number of the directory hashing table. 






Ll 
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DISK PARAMETER BLOCK— DPB 



SPT BSH BLM £XM DSM DRM ALO ALl CKS OFF PSH PHM 

16b 8b 8b 8b 16b 16b 8b 8b 16b 16b 8b 8b 

SPT Number of 128 records per track 

BSH Data allocation block shift factor 

BLM Block mask 

EXM Extent mask 

DSM Number of allocation block on disk minus one 

DRM Number of directory entries minus one 

ALO First byte: directory block allocation vector. Filled from MSB to LSB 

ALl Second byte: (Up to 16 allocation blocks can be used for the directory) 

; i CKS Sizeof the directory check vector, (DRM +l)/4 

OFF Number of reserved tracks at the beginning of the disk 

p PSH Physical record shift factor 

I I PHM Physical record mask 

( I 

BUFFER CONTROL BLOCK (LRU CONTROL BLOCK— BCB) 

( i ■■ 

/ ! DRV REC# WFLG 00 TRACK SECTOR BUFFAD BANK LINK 

8b 24b 8b 8b 16b 16b 16b 8b 16b 

r-i . 

I i 

' ^ DRV Drive associated with this record. Set to OFFH when not used. 

REC# Contains the absolute sector number of the buffer. 

~7 WFLG Set to OFFH when buffer contains data that must be written to disk. 

I 00 Scratch byte used by BDOS 

TRACK Physical track address of buffer. 

SECTOR Physical sector address of buffer. 

I ; BUFFAD Address of the buffer associated with this BCB. 

' 1 BANK Bank number of buffer associated with this BCB. 

LINK Contains the address of the next BCB in this linked list. Set to zero if last. 



COMMODORE 128 SYSTEM DEPENDENT 
USER FUNCTIONS 



The Z80 machine language routines discussed in this section pertain explicidy to the 
Commodore 128 Personal Computer. These routines are not part of the standard CP/M 
system that is transportable from one manufacturer's computer to another. They are 
written to run only on the Commodore 128. 

Most of these customized CI 28 Z80 routines require certain parameters to be 
passed from the user into the appropriate Z80 registers. All these routines, listed by 



686 COMMODORE 128 



its 1 & 







= lower case 


1 


= uppercase 


1 


= shifted 


1 1 


= control key 



u 



function number, require that the function number be placed in the Z80 A register 

(accumulator). Many of these routines have subfunctions which require the user to place 

a value in the eight bit L register, which is used to call the appropriate subfunction. All 

other additional required parameters are noted if they are necessary. This section follows [j 

the same format as the preceding CP/M BIOS section: 



» / 






a) Function Name 

b) Input Parameters 

c) Output Parameters 

d) Brief Description | j 

e) Additional Information l_j 

a) User Function 0: Read any Byte in RAM Bank 00 

b) A = (function number) | / 
DE = 16 bit address to be read i_j 

c) C= Value read from address in RAM Bank 

A = on RETum from routine , 

d) This reads a value from RAM BANK ($0-$OFFF, $1000-$FFFF RAM) j 
and places it in register C. 

I. a) User Function 1: Write Function in RAM Bank , ^ 

b) A = 1 (function number) j ) 
DE = 16-bit address where write operation occurs 

C = Value to be written to the ad(kess in Bank 

c) A = on RETum from routine if write is successful | 
A = -1 ($FF) on RETum from routine if write is unsuccessful i_ 

d) This function writes the value in register C to RAM in bank specified 
by the address in register pair DE. An error is flagged if a write to ROM 
($0-$DFFFH) or the top page of memory ($FF00-$FFFF) is attempted. 

II. a) User Function 2: Keyscan Function 

b) A = 2 (function number) | i 

c) B = -1 ($FF) if no key is pressed [J 
B = Matrix position in the keyboard matrix table (if pressed) 

A = Contents (character value) of matrix position whether A is lower- or 

uppercase or containing the C O N T R O L key. j, | 

HL = Address (pointer) where A (contents of matrix position) is found *— ' 

in memory 

Address = Tablestart + (4 * B) -I- C (bits 1 and 0) \ 

C = Returns control code information, where each bit has a specific \ 

meaning as follows: 



L 
LJ 



u 
u 
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C = Bit 2 1 = control key down, = up 

Bit 3 Not implemented 

Bit 4 1 = Right shift key down, = up 

Bit 5 1 = O key is active (not necessarily down) 

Bit 6 Not implemented 

Bit 7 1 = left shift key down, = up 

d) The keyscan function allows the user to bypass the normal I/O BIOS 
keyboard processing and check for a particular key or key sequence 
being pressed. 

e) Additional Information — ^Important Addresses: 

$FD09 = Pointer to Tablestart (low byte first) 

Each ASCII character has four coded defiriitions. Each key has a defined code for 
the following: 

a) lower case 

b) upper case 

c) shifted key and character 

d) control key and character 

These four definitions are labeled in columns in the ASCII table. 



n 



I I 

! I 



n 

n 





ASCn$TBL: 


A B C D 




1292 7F7F7F16 


DB 


7FH,7I'H,7FH,16H 


, INS DEL matrix position 


1296 ODODODOD 


DB 


0DH,0DH,0DH,0DH 


.RETURN 


129A 06060101 


DB 


06H,06H,01H,01H 


LFRT 


129E 86868787 


DB 


86H,86H,87H,87H 


F7F8 


12A2 80808181 


DB 


80H,80H,81H,81H 


F1F2 


12A6 82828383 


DB 


82H,82H,83H,83H 


F3F4 


12AA 84848585 


DB 


84H,84H,85H,85H 


F5F6 


12AE 1717171A 


DB 


17H,17H,17H,1AH 


UP DOWN 


12B2 333323A2 


DB 


33H,33H,23H,0A2H 


3# 


12B6 77575717 


DB 


77H,57H,57H,17H 


W 


12BA 61414101 


DB 


61H,41H,41H,01H 


A 


12BE 343424A3 


DB 


34H,34H,24H,0A3H 


4$ 


12C2 7A5A5A1A 


DB 


7AH,5AH,5AH,1AH 


Z 


12C6 73535313 


DB 


73H,53H,53H,13H 


s 


12CA 65454505 


DB 


65H,45H,45H,05H 


E 


12CE 00000000 


DB 


0OH,00H,00H,0OH 


(LF SHIFT) 


12D2 353525A4 


DB 


35H,35H,25H,0A4H 


5% 


12D6 72525212 


DB 


72H,52H,52H,12H 


R 


12DA 64441404 


DB 


64H,44H,44H,04H 


D 


12DE 363626A5 


DB 


36H,36H,26H,0A5H 


6& 


12E2 63434303 


DB 


63H,43H,43H,03H 


C 




DB 


66H,46H,46H,06H 


F 



1 
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\SCn$TBL: 


12EA 


74545414 


DB 


12EE 


78585818 


DB 


12F2 


373727A6 


DB 


12F6 


79595919 


DB 


12FA 


67474707 


DB 


12FE 


383828A7 


DB 


1302 


62424202 


DB 


1306 


68484808 


DB 


130A 


75555515 


DB 


130E 


76565616 


DB 


1312 


39392900 


DB 


1316 


69494909 


DB 


131A 


6A4A4A0A 


DB 


131E 


30303000 


DB 


1322 


6D4D4D0D 


DB 


1326 


6B4B4B0B 


DB 


132A 


6F4F4F0F 


DB 


132E 


6E4E4E0E 


DB 


1332 


2B2B2B00 


DB 


1336 


70505010 


DB 


133A 


6C4C4C0C 


DB 


133E 


2D2D2D00 


DB 


1342 


2E2E3E00 


DB 


1346 


3A3A5B7B 


DB 


134A 


40404000 


DB 


134E 


2C2C3C00 


DB 


1352 


23232360 


DB 


1356 


2A2A2A00 


DB 


135A 


3B3B5070 


DB 


135E 


000000F5 


DB 


1362 


00000000 


DB 


1366 


3D3D3D7E 


DB 


136A 


5E5E7C7C 


DB 


136E 


2F2F3F5C 


DB 


1372 


313121A0 


DB 


1376 


5F5F5F7F 


DB 


137A 


09153000 


DB 


137E 


323222A1 


DB 


1382 


20202000 


DB 


1386 


21200000 


DB 


138A 


71515111 


DB 


138E 


OOOOOOFO 


DB 



74H,54H,54H,14H 
78H,58H,58H,18H 

37H,37H,27H,0A6H 

79H,59H,59H,19H 

67H,47H,47H,07H 

38H,38H,28H,0A7H 

62H,42H,42H,02H 

68H,48H,48H,08H 

75H,55H,55H,15H 

76H,56H,56H,16H 

39H,39H,29H,00H 
69H,49H,49H,09H 
6AH,4AH,4AH,0AH 
30H,3OH,3OH,0OH 

6DH,4DH,4DH,0DH 
6BH,4BH,4BH,0BH 
6FH,4FH,4FH,0FH 
6EH,4EH,4EH,0EH 

2BH,2BH,2BH,00H 

70H,50H,50H,10H 

6CH,4CH,4CH,0CH 

2DH,2DH,2DH,00H 

2EH,2EH,3EH,00H 

3AH,3AH,5BH,7BH 

40H,40H,40H,00H 

2CH,2CH,3CH,00H 

23H,23H,23H,60H 

2AH,2AH,2AH,00H 

3BH,3BH,5DH,7DH 

00H,0OH,0OH,0F5H 

00H,00H,00H,00H 

3DH,3DH,3DH,7EH 

5EH,5EH,7CH,7CH 

2FH,2FH,3FH,5CH 

31H,31H,21H,0A0H 
5FH,5FH,5FH,7FH 
09H,15H,30H,00H 

32H,32H,22H,0A1H 

20H,20H,20H,00H 

21H,20H,00H,00H 

71H,51H,51H,11H 

00H,00H,O0H,OFOH 



T 
X 

7' 

Y 

G 

8{ 

B 

H 

U 

V 

9) 
I 
J 


M 
K 
O 

N 

+ 
P 
L 



w 
,< 

POUND 

* 

;]} 

CLEAR/HOME 
(RT SHIFT) 

PI 

/?\ 

1 

<- 

(CONTROL) SOUNDl 
S0UND2 
2" 

SPACE 

(COMMODORE) S0UND3 
Q 
RUN STOP 



J 

U 

u 
li 



U 
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ASCn$TBL: 


A B C D 


1392 


9F9F9F9F 


DB 


9FH,9FH,9FH,9FH 


1396 


383838B7 


DB 


38H,38H,38H,0B7H 


139A 


353535B4 


DB 


35H,35H,35H,0B4H 


139E 


09090900 


DB 


09H,09H,09H,00H 


13A2 


323232B1 


DB 


32H,32H,32H,0B1H 


13A6 


343434B3 


DB 


34H,34H,34H,0B3H 


13AA 


373737B6 


DB 


37H,37H,37H,0B6H 


13AE 


313131B0 


DB 


31H,31H,31H,0B0H 


13B2 


IBIBIBOO 


DB 


1BH,1BH,1BH,00H 


13B6 


2B2B2B00 


DB 


2BH,2BH,2BH,00H 


13BA 


2D2D2D00 


DB 


2DH,2DH,2DH,00H 


13BE 


OAOAOAOA 


DB 


0AH,0AH,0AH,0AH 


13C2 


ODODODFF 


DB 


0DH,ODH,ODH,OFFH 


13C6 


363636B5 


DB 


36H,36H,36H,0B5H 


13CA 


39393900 


DB 


39H,39H,39H,00H 


13CE 


333333B2 


DB 


33H,33H,33H,0B2H 


13D2 


00000000 


DB 


OOH,O0H,O0H,OOH 


13D6 


30303000 


DB 


30H,30H,30H,00H 


13DA 


2E2E2E00 


DB 


2EH,2EH,2EH,00H 


13DE 


05050512 


DB 


05H,05H,05H,12H 


13E2 


18181803 


DB 


18H,18H,18H,03H 


13E6 


1313138D 


DB 


13H,13H,13H,08DH 


13EA 


0404048E 


DB 


04H,04H,04H,08EH 


13EE 


F1F1F1F2 


DB 


0F1H,0F1H,0F1H,0F2H 



/HELP/ 

/8/ 

ISI 

/TAB/ 

121 

141 

111 

III 

/ESC/ 

/+/ 

l-l 

/LINE FEED/ 

/ENTR/ 

161 

191 

131 

/ALT/ 

101 

1.1 

/UP/ 

/DN/ 

/LF/ 

/RT/ 

/NO SCROLL/ 



LOGICAL COLOR TABLE (USED WITH ESC ESC ESC CHAR) 

(WHERE CHAR IS 50H TO 7FH) 



13F2 00112233 

13F6 44556677 

13FA 8899AABB 

13FE CCDDEEFF 



DB 000H,011H,022H^H 

DB 044H,055H,066H,07^H 

DB 088H,099H,0AAH,0BBH 

DB 0CCH,0DDH,0EEH,0FFH 



III. a) User Function 3: Execute a Z80 ROM function 

b) A = 3 

L = subfunction number 
Additional input parameters may be necessary 
, c) Most of the ROM functions do not output values; they instead perform 
an action, which in this user function is assumed to be the output. 

d) This function executes a Z80 ROM function. These ROM routines 
primarily perform screen manipulation routines. 
All subfunction numbers are even numbers. The first 80 subfunctions are 
screen manipulating routines for the 40- and 80-column display. Only the 
80-column subfunction is listed here. Add 2 to the 80-column subfunction 
number to get the corresponding 40-column subfunction number. 
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III. Oa) Subfunction 0: Write Character 

b) wr$char 

c) Register D = character to write auto advance cursor to next position 
d) 

III. 4a) Subfunction 4: Cursor Position 
b) cursor$pos 

c) Register D = row value 
Register E = column value 

d) This subfunction sets the current position of the cursor on the 80-column 
screen. 



u 



u 



III. 8a) Subfunction 8: Cursor Up one position 

b) cursor$up 

c) no values returned 

d) This subfunction moves the cursor up one row on the current screen (40 
or 80), but not past the top of the screen. 

III. 12a) Subfunction 12: Cursor down one row 

b) cursor$down 

c) no values returned 

d) This subfunction moves the cursor down one row on the current screen J 
(40 or 80). The screen scrolls down if on bottom line. U 

III. 14a) Subfunction 14: Not Implemented 
b) 

c) U 

III. 16a) Subfunction 16: Cursor left one column 

b) cursor$left | 

c) no values returned Lv 

d) This subfunction moves the cursor left one column, but not past the 

left margin. i 

III. 20a) Subfunction 20: Cursor right one colunm U 

b) cursor$rt 

c) no values returned. ^ i 

d) This subfunction moves the cursor right one column, but not past the [ J 
right edge of the screen. 

III. 24a) Subfunction 24: Execute a carriage return 

b) do$cr 

c) No values returned. 

d) This subfunction executes a carriage return and places the cursor at the 

left margin. I 

III. 28a) Subfunction 28: Clear to end of line 

b) CEL 

c) No values returned. 

d) This subfunction clears the cursor row starting where the cursor is L 
currently located and ending at the end of the line. 
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III. 32a) Subfunction 32: Clear to end of screen 

b) CES 

c) No values returned. 

d) This subfunction clears the screen starting where the cursor is currently 
located through the end of screen. 

III. 36a) Subfunction 36: Character insert 

b) char$ins 

c) No values returned. 

d) This subfunction inserts a character at the current cursor position, the 
last character on the line is lost. 



in. 40a) Subfunction 40: character delete 
1 b) char$del 

! c) No values returned. 

d) This subfunction deletes a character at the current cursor position, and 
places a space in the last position in the line. 

in. 44a) Subfunction 44: Line insert 

b) line$ins 

c) No values returned. 

d) This subfunction inserts a line of spaces on the current cursor row, the 
current cursor row is moved down one and the last line (24) is lost. 

III. 48a) Subfunction 48: Line delete 

b) line$del 

c) No values returned. 

d) This subfunction deletes a Une at the character row marked by the 
current cursor position. The bottom line (24) is filled with spaces. 

III. 50a) Subfunction 50: Not Implemented 

b) 

c) 

d) 

III. 52a) Subfunction 52: Set Cursor Color 

b) color 
B register returns color code value 

c) No values returned. 

d) This function sets the current cursor color code with the value in color. 

III. 56a) Subfunction 56: Set 80-column Attributes 

b) attr 
B = bit to set/clear 
C = bit value 

c) No values returned. 

d) This function enables/disables the 8563 attributes for the 80-column screen. 
Attributes are extra screen features such as foreground R,G,B and I, 
character blinking, underlining, reverse video and the alternate character 
set. The 40-column function (subfunction 58) controls only reverse video. 
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III. 60a) Subfunction 60: Read Character Attribute (80) 

b) rd$chr$atr 

D = 8563 character row 

E = 8563 character column '— ' 

c) D = 8563 character row 

L = 8563 character column | | 

B = character value [J 

C = attribute bit pattern of selected character location 

d) This function reads the attribute byte of the selected character row and . 
column on the 8563 screen, and returns the true RGBI color. The 
corresponding 40-column subfunction (62) controls only reverse video. 

III. 64a) Subfunction 64: Write Character Attribute (80) , . 

b) wr$chr$atr | 

B = character value 
C = attribute 

c) No values returned 

d) This function writes an attribute byte of the selected character value 
on the 8563 screen. 

m. 68a) Subfunction 68: Read Color 

b) rd$color L 

c) A = character color 
B = background color 
C = border color (40-colunm only) 
D = 8563 attribute 

d) This function reads the cunent color of the 8563 color sources. Subfunction 
70 returns the VIC color sources. 

III. 80a) Subfunction 80: Convert record (OCR only) 

b) @trk 

c) VIC$trk, VIC$SEC 

d) This function returns the physical track and sector from the disk drive, 
including skew, given the logical track. 

III. 82a) Subfunction 82: Check CBM code from disk (GCR only) j 

b) check$CBM jj 

c) zero flag = 1 if CBM (CI 28 mode disk) is present in drive 
zero flag = if CP/M 2.2 (C64 CP/M disk) is present in drive 
A = if single sided 
A = $FF if double sided 

d) This function detects which type of GCR disk is in the drive. Reads 
data from t = 1 , s = into buffer at $FE00. 



u 



III. 84a) Subfunction 84: Bell Function 

b) Sound 1, Sound 2, Sound 3 ($FD10, $FD12, $FD14, respectively) 

c) Outputs a bell sound . 

d) This function outputs a bell sound from the SID chip. 

Subfiinctions 86-95 are not defined '~ 
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m. 96a) Subfunction 96: Track 40 

b) trk$40 

c) @ off 40 

d) This function computes the logical (offset) position of the cursor on the 
physical 80-column screen. The variable @ off40 is computed on 
8-character boundaries, and is used in the next subfunction. 

III. 98a) Subfunction 98: Set cursor position 

b) set$cur$40 

c) No value returned. 

d) This function calls Track 40 to check the offset between the logical 
(window) and physical (40-column) screen. It keeps the cursor within 
the 40-column logical window on the scrolled SO-column virtual screen 
for VIC screen output. 

III. 100a) Subfunction 100: Line Paint 

b) line$paint 

c) No value returned. 

d) This function updates the current character line only if @ off 40 and 
old $offset are the same. If old $offset =-1, TRACK 40 is called. 
If @off40 and old $offset are not equal, Screen Paint is called to 
scroll the 40-column logical screen (window) over the virtual SO- 
column screen. 



III. 102a) Subfunction 102: Screen paint 

b) screen$paint 

c) No value returned. 

d) This function updates (scrolls) the 40-column logical (window) screen 
across the VIC 80-column virtual screen based on the value of @off40. 
This and the three previous subfunctions (96, 98, 100) are intertwined 
to make the scrolled 40-column logical screen display as fast as 
possible. Normally you would only call Set Cursor Position or Line 
Paint, since they call the other related routines, if necessary. See file 
CXROM.ASM listing on the DRI disks that come with the documenta- 
tion for the source Ustings. 

III. 104a) Subfunction 104: Print Message (BOTH) 

b) prt$msg$both 

c) No value returned. 

d) This function prints simultaneous output to both screens, displaying 
the string pointed to by the top value on the stack. Place the address of 

_ the string on the stack, and terminate the string with a zero. Execution 

I resumes with the byte following the zero terminator. This works like 

' I an "in Una Drint" 
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an "in-line Print' 

III. 106a) Subfunction 106: (Print Message (BOTH) 

b) prt$de$both 

c) No value returned. 
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d) This function works like the previous one, except the start address of 
the string is taken from DE, and execution resumes with the return 
address from the stack. 



u 



III. 108a) Subfiinction 108: Incripted Messages 

b) update$it I i 

c) No value returned j 

d) This function displays incripted messages. '-' 
Subfunction 110 is not implemented. 

in. 112a) Subfunction 112: ASCn to PET ASCU Conversion | 

b) ASCn$pet, B register = ASCII character ($20-$7F) ^ 

c) A register = converted PET ASCII character. 

d) This function performs a standard ASCII to Pet ASCII conversion on 
the characters printed to the' screen (from any input device) 
Control codes are not translated. 

III. 114a) Subfunction 114: Place 40-column cursor at specified address j j 

b) cur$adr$40 U 

c) HL = address of cursor on screen 
DE = cursor line (row) start address 
BC = # of characters to end of line (<80, not counting cursor) 

d) This function places the cursor at the address specified in HL (in RAM 
bank 0). This address is of the logical screen, not the virtual one. 

III. 116a) Subfunction 116: Place 80-colunm cursor at specified address 

b) cur$adr$80 

c) HL = address of cursor on screen 
DE = cursor line (row) start address 
BC = # of characters to end of line (<80, not counting cursor) 

d) This function places the cursor at the address specified in HL (in 
8563 RAM). 

III. 118a) Subfunction 118: Look up color 

b) look$color, B = color code ($30-$3F), C = max. Value of color code. 

c) HL = pointer to logical color table (lower nybble = 80, high nybble = 40- 
B = $0 (Character color) 

$10 (Background color) 
$20 (Border color) 

d) This function sets the 8563 screen colors to the VIC screen colors. 
Subfiinction 120 is not defined. 

in. 122a) Subfunction 122: Block Fill 

b) blk$fill, put start address on stack (8563) 
BC = # of bytes to fill 

D = fill character 
E = attribute 

c) No value returned. 

d) This function fills a 256-byte block with data specified in the D register. 
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m. 124a) Subfunction 124: Block move 

b) blk$move, place source address (in 8563 RAM) on the stack 
DE = destination address (in 8563 RAM) 

BC = count 

c) No value returned. 

d) This function moves 256-byte blocks from one memory block to another 
in 8563 RAM. 



NOTE: Subfunctions 122 and 124 and 126 must be direct Z80 calls. The 
example routines provided in this section for subfunctions 122, 124 and 126 
will not woik. ITiey are usually not user-accessible, and must run in BANK 0. 
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III. 126a) Subfunction 126: Character Install 

b) chr$inst, stack = 8563 RAM address to install character definition 
DE = address of system memory (C128 RAM) bank 0) of new 

character definition (8 bytes per character). 
B = number of consecutive characters 

c) No value 

d) This function installs a user-defined character in 8563 RAM. 

IV. a) User Function 4: 8502 BIOS Functions 

b) A = 4 (function number) 

L = Subfunction number (-1 through 11) 

Additional input parameters may be required 

c) Outputs depend on each subfunction 

d) User function 4 allows you to call 8502 input/output functions that are 
performed by the 8502 processor. These functions are not part of the 
standard CP/M system and are completely hardware-dependent. This 
function enables you to go back and forth between the Z80 and 8502 
processors. 

e) Each subfunction is discussed in detail using the defined conventions. 

IV. -1. a) Subfunction -1: Reboot C128 hardware 

b) A = 4 
L = -1 

c) none 

d) This subfunction reboots the Commodore 128 hardware when the value 
in the L register is equal to -1 ($FF). This subfunction is not normally 
used. It performs the same actions as pressing reset. 

IV. O.a) Subfunction 0: Initialize 8502 BIOS 
b) A = 4 
L = 
cl) Sets up interrupt vector $0314-$0319 to vector to the 8502 interrupt 

handler 
c2) Copies ROM interrupt vector to RAM 
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c3) Sets up PAL and NTSC variables (SYSFREQ) 

c4) Closes all open channels 
d) This subfunction intializes 8502 system variables, interrapt processing j 

and system frequencies so that the Z80 and 8502 may conmiunicate ^ 

back and forth. Processor control is given to either the Z80 or the 8502 
at one particular time. The processors cannot run simultaneously. j ', 

IV. l.a) Subfunction 1: 1541 Read (GCR format only) '-' 
b) A = 4 

L = 1 j 

VICTRACK = (1-35)— Variable for track number on disk L 
VICSECTOR = (0-21) — ^Variable for sector number on disk 

VICDRV = — Variable for disk drive device number where: , 



LOWER NYBBLE 






EQUIVALENT OPEN 


OF VICTORY 








BIT VALUE 


DEVICE NUMBER 


DRIVE 


STATEMENT IN BASIC 


0001 
0010 
0100 
1000 


8 

9 

10 

11 








OPEN 8,11,15 
OPEN 9,12,16 
OPEN 10,13,17 
OPEN 11,14,18 



Values of the Lower Nybble of VICDRV 

c) VICDATA = 1 1 ($0B) if disk in drive has been changed L 
VICDATA = 13 ($0D) if read/write or channel error occurs 

VICDATA = if read is successful j 

VICDATA = 15 ($0F) if device is not present I 

d) This fiinction reads a particular track and sector on the disk in the drive 
as specified by VICTRACK and VICSECTOR and VICDRV respec- 
tively. Data is read into the buffer at $FE00H. The value returned in the 

variable VICDATA depends on the conditions described in c. L 

e) Additional Information: This subfunction assumes that both the data and 
command channels have been opened previously. An error will occur if 
this routine is called to read fi-om a 1571. 

IV. 2.a) Subfunction 2: 1541 Write (GCR format only) 

b) A = 4 
L = 2 

VICTRACK = Same as for 1541 Read '-J 

VICSECTOR = Same as 1541 Read 

VICDRV = Same as 1541 Read j 

c) VICDATA = Same as 1541 Read |J 

d) This subfunction writes data to the specified track and sector on the disk 
in the drive as specified by VICTRACK, VICSECTOR and VICDRV 
respectively. The value returned in VICDATA depends on the condi- 
tions described for the outputs in c. See subfunction 1 for details. ^ 
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e) Additional Information: This subfiinction assumes that both the data and 
^^ command channels have been opened previously. Data is written from 

j j the buffer at $FEOOH. 

IV. 3.a) Subfiinction 3: 1571 Read Set Up (MFM or GCR formats) 

b) A = 4 
M L = 3 

' ' * VICTRACK = (1-35)— Variable for track number on disk 

* VICSECTOR = (Q-21)— Variable for sector number on disk 

* VICDRV = —Variable for disk drive device number (See VICDRV 
table above.) 

* = Ranges apply to GCR format only. The ranges are different for 
MFM disks depending on the manufacturer. 

VIC$COUNT = Number of sectors to read (on the track) 

c) VICDATA = 11 ($0B) if disk in drive has been changed 
VICDATA = 12 ($0C) if drive is not a fast (1571) disk drive 
VICDATA = 13 ($0D) if channel error occurs 
VICDATA = 15 ($0F) if device is not present 
If FAST ANDed with VICDRV = meaning drive is a 1541 
If FAST ANDed with VICDRV = 1 meaning drive is a 1571 

d) This subfunction sets up the 1571 disk drive for a read operation. 
However, the data transfer is not performed by the 8502 BIOS. The 
data is transferred by the Z80. 

e) Additional Information: To access the back side of an MFM disk set bit 
7 ($80) of VICSECTOR. For MFM formats, a dash between the track and 
sector on the display window means that the drive accesses the back 
side of the disk. This is usually performed by the BIOS. 

IV. 4.a) Subfiinction 4: 1571 Write Set Up (MFM or GCR formats) 
b) A = 4 
L = 4 

* VICTRACK = (1-35)— Variable for track number on disk 

* VICSECTOR = (0-21)— Variable for sector number on disk 
VICDRV = —Variable for disk drive device number. See VICDRV 

table on previous page. 
VIC$COUNT = Number of sectors to read 

* = Ranges apply to GCR format only. The ranges are different for 
n MFM disks depending on the manufacturer. 

j ! c) VICDATA = 11 ($0B) if disk in drive has been changed 

VICDATA = 12 ($0C) if drive is not a fast (1571) disk drive 
VICDATA = 13 ($0D) if channel error occurs 

n VICDATA = 15 ($0F) if device is not present 

i ! If FAST ANDed with VICDRV = meaning drive is a 1541 

If FAST ANDed with VICDRV = 1 meaning drive is a 1571 

f^ d) This subfunction sets up the 1571 disk drive for a write operation. 

However, the data is not performed by the 8502 BIOS. The data is 
transferred by the Z80. 
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e) Additional Information. This is how the user should select between a 
1541 and 1571 Drive. To access the back side of an MFM disk set bit 7 
of VICSECTOR. To perform a write operation, the user will have to do 
so in their application. 

IV. 5.a) Subfunction 5: Interrogate 1541 or 1571 Disk Drive 

b) A = 4 
L = 5 
VICDRV = (8-11) — ^Disk drive device number variable 

c) VICDATA = lower four bits returns status for FAST read/write 

(same as previous VICDATA Disk error codes, which 
are listed in the Disk Error Status table on the next page). 
= upper four bits return sector size for MFM disks 

d) This subfunction interrogates the disk drive for the disk sector size 1 | 
(MFM or GCR) and the drive status. In addition, this subfunction ^ 
initializes the FAST variable, closes and reopens the channel for the 
corresponding drive, and clears the drive status. j 

IV. 6.a) Subfunction 6: Query to Disk U 

b) A = 4 

L = 6 I 

VICTRACK = (1-35)— Variable for track number on disk | 

VICSECTOR = (0-21)— Variable for sector number on disk 
VICDRV = — Variable for disk drive device number 

c) If error-free 
VICDATA = lower four bits returns status for FAST read/write 

= upper four bits return sector size for MFM disks and the 
subfunction inputs 6 bytes into a memory buffer starting at 
location $FEOO (and ending at $FEFF). These 6 bytes are 
defined as : 



u 





1) $FEOO-TRACK STATUS (on track below) j 

2) $FE01-Number of Sectors '^ 

3) $FE02-Logical Track 

4) $FE03-Minimum Sector Number (on this track) 

5) $FE04-Maximum Sector Number (on this track) L 

6) $FE05-PhysicaI Interleave 

If an error occurs: j { 

VICDATA = 1 1 ($0B) if disk in drive has been changed ^ 

VICDATA = 12 ($0C) if drive is not a fast (1571) disk drive 
VICDATA = 13 ($0D) if channel error occurs 

VICDATA = 15 ($0F) if device is not present ^ 

d) This subfunction queries the disk, and returns the disk status and sector 
size (if MFM format). In addition, the buffer located between $FEOO 
and $FEFF receives 6 data items as described above. 
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Disk Error Status Table 



MD DN II 12 Dl D2 D3 04 

MD Mode: 1 = MFM, = GCR. 

DN Drive Number. 

II, 12 Sector Size. 

a) 00 = 128 bytes 

b) 01 = 256 bytes 

c) 10 = 512 bytes 

d) 11 = 1024 bytes 

D1-D4 Controller Status 

GCR 



OOOx = Ok. 

0010 = Sector not found. 
n 0011 = No Sync. 

j I 0100 = Data block not found. 

0101 = Data block checksum. 

0110 = Format error. 

0111 = Verify error. 

1000 = Write protect error. 

1001 = Header block checksum. 

1010 = Data extends into next block. 

1011 = Disk ID mismatch/Disk change. 

1100 = Drive is not fast (1571). 

1101 = Channel Error. 

1110 = Syntax. 

1111 = No Drive present. 



_ MFM 

j I OOOx = Ok. 



n 

n 
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0010 = Sector not found. 

0011 = No address mark. 

0100 = Unused. 

0101 = Data CRC error. 
0110 = Format error. 

^ 0111 = Verify error. 

.' I 1000 = Write protect error. 

• ^ 1001 = Header CRC error. 

1010 = Unused. 
f~^ 1011 = Disk change. 

j I 1100 = Drive is not fast (1571). 

1101 = Channel Error. 

1110 = Syntax. 
r^ 1111 = No Drive present. 



Disk Error Status Table 

n 
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IV. 7. a) Subfunction 7: Print characters to a serial bus printer 

b) A = 4 
L = 7 

VICDRV = Printer number (either 4 or 5) 
VICTRACK = Secondary address in which device is opened as 
VICDATA = Character to be printed to the serial bus printer (if 
VICCOUNT=0) 

c) VICDATA = -1 ($FF) if device is not present 

d) This subfunction outputs characters to the previously opened serial bus 
printer. 

e) Additional Information: If the secondary address (which is normally 7) 
is changed, the device is closed and reopened with the new secondary 
address. If a serial bus error besides device not present occurs, the 
channel is closed, reopened and the original operation is executed 
again. 

If VICCOUNT is not equal to zero, the data is printed firom the buffer 
pointed to by $FE(X). The number of bytes printed is supplied in VICCOUNT. 
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IV. 8.a) Subfunction 8: Format a 1541 or 1571 Diskette 

b) A = 4 
L = 8 
DRIVE# 
FAST 

c) VICDATA 

d) This subfunction formats a 1541 or 1571 diskette in the appropriate 
drive. If FAST is enabled, (FAST ANDed with DRIVE# (not equal to 

0)), the length of a disk command is fetched from memory buffer j | 

location $FE(K). The command starting at location $FE01 and ending at jj 

the location specified by the length of the command in $FEOO is sent to 
the drive. For example, if $FEOO = $06, the conmiand in the memory , . 

buffer between $FE01 and $FE06 is sent to the drive. All commands | I 

have a "UO" preceding them, so only the command from the memory ^ 

buffer must be supplied. 

IV. 9.a) Subfunction 9: User Call to 8502 Code Routine 

b) A = 4 ^ 
L = 9 

VICOUNT = ($FD05) low byte address of 8502 routine (pointer to the 

start of execution of the user routine) 
VICDATA = ($FD06) high-byte address of 8502 routine 

c) User defined outputs only I / 

d) This is the routine that allows you to call an 8502 machine language jj 
subroutine from Z80 mode. The 8502 coded routine is usually user 

defined. It must execute in RAM bank with the input/output registers 
enabled. The MMU value = $3E. Control is transferred to the 8502 
processor with the KERNAL disabled. If you want to call a C128 
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KERNAL routine, you must enable the KERNAL after you have trans- 
^ ferred control to the 8502. Before you return to the Z80, you must 

I I disable the KERNAL again. 

' * When control passes from the Z80 to the 8502 processor, the Z80 

is idle. To return control to the Z80 processor, place the customary 
r] 8502 RTS instruction at the end of your 8502 coded routine and control 

I \ is passed back to the Z80. 

e) Additional Information: Once control is passed from the Z80 to the 
p 8502, the 8502 is running at the speed of 1 Mhz. You can increase the 

I ! speed to 2 Mhz to speed up processing on the 8502 side of the 

computer. However, YOU MUST RETURN TO 1 Mhz SPEED BEFORE 
^ RETURNING TO THE Z80 OR A SYSTEM CRASH WILL OCCUR. 

j I The nature of the timing of the two processors dictates this. If you 

' ' don't return to 1 Mhz, the clock cycle timing is thrown off and the 

system crashes. 

' ) IV. lO.a) Subfunction 10: RAM Disk Read 

'I b) A = 4 

L = 10 
P c) Data is transferred to expansion RAM from RAM (BANK 0) 

d) All expansion RAM registers must be set up prior to calling this routine. 

IV. 11. a) Subfunction 11: RAM Disk Write 

b) A = 4 
L = 11 

c) Data is transferred to expansion RAM from RAM (BANK 0) 

d) All expansion RAM registers must be set up prior to calling this routine. 

V. a) User Function 5: Read 40/80 Column Key 

b) A = 5 (function number) 

PI c) A = Value stored in $D505 (CI 28 Mode Configuration register) 

j I If bit 7 is high (1), 40/80 key is up, otherwise 40/80 is down. 

d) This function returns the value of location $D505, the mode configura- 

,^ tion register. Only bit 7 is significant as noted above. The 40/80 key is 

j [ not in the keyboard matrix table, so this function is dedicated to reading 

' ' its position. 

^^ VI. a) Functions 6 through 254 are not implemented. 

I I b) none 

' ' c) HL = number of days (in binary) since 1/1/78 

^ VII. a) User Function 255: System Date 

j I b) A = -1 ($FF) 

c) HL = number of days (in binary) since 1/1/78 

d) By specifying A = -1, the system date is returned. 
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PART II 

CALLING CP/M BIOS, 8502 BIOS AND 
CP/M USER FUNCTIONS IN 
Z80 MACHINE LANGUAGE 



D 
U 
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The Commodore 128 CP/M system allows you to call the CP/M BIOS, 8502 BIOS and 
CP/M user functions in your own Z80 assembly language programs. However, in order 
to program in Z80 assembly language, you need either an assembler or machine 
language monitor. Many Z80 assemblers and monitors are available on the market; i 

however, the full featured Digital Research CP/M Plus (3.0) system now available on ^ 

the Commodore 128 comes with two Z80 assemblers, MAC and RMAC and CP/M plus 
documentation. These programs or documentation are not included in the Commodore | 

128 Personal Computer package; refer to the Commodore 128 System Guide for infor- i^ 

mation on obtaining them. 

Assuming you have the MAC and RMAC assemblers, you can now enter and ^ 

assemble Z80 assembly language programs. At this point, this reference guide must j 

make a substantially large assumption about its readers and their knowledge of Z80 '-' 

assembly language programming. As you probably agree, this reference guide could not 
possibly introduce Z80 machine language and thoroughly cover it. That is simply j | 

beyond the scope of this book, considering how voluminous it is already. Your trusty LI 

local bookstore undoubtedly offers several excellent books on Z80 progranuning. See 
"Suggestions for Further Reading" for a few Z80 book titles. r < 

Now that all the assumptions are out of the way, here's how to call a Z80 user or i I 

BIOS function. First, the user function call. 

CALLING A CP/M SYSTEM USER FUNCTION [ 

As you saw in Part I of this appendix, certain user functions had subfunctions, others 
did not. User function 4 is the 8502 BIOS call function. The 8502 BIOS functions have 
13 (-1-11) subftinctions which perform the machine level 8502 input and output L, 

routines. Do not conftise the 8502 BIOS with the CP/M BIOS. The CP/M BIOS comes 
standard with every CP/M Plus system regardless of the hardware running it. Remember 
that CP/M was designed to be transportable from one microcomputer to another. Each 
different microcomputer has its own machine level input and output which it must 
perform. The 8502 BIOS is completely hardware-dependent and will only run on the 
Commodore 128's 8502 microprocessor. 

Another way of understanding the difference between the two BIOS types is 
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recalling the CP/M jump vector on page 677 of Appendix K. The first 30 jumps (0-29) 
are direct calls to CP/M BIOS routines. Jump number 30 is the call to the user functions, of 
which user function 4 is the 8502 BIOS. The 8502 BIOS is a subset of the CP/M user 
functions. The user function call is 1 of 31 system routine calls within the CP/M BIOS 
jump table. 

The following example calls user function 2 the keyscan function. The calling 
routine starts at "waitkey" and the subroutine starts at "userSfiin". 



waitkey: 



MVI useroffset,30 

MVI A,2 
CALL user$fun 
INRB 
JZ waitkey 
DCRB 



Rest of Program 



; load A reg. with function no. 2 

;calls subroutine userSfiin 

increment B — test for -1 if no key is pressed 

;jump to wait key if none 

;decrement B if B not equal to 

;this restores original matrix value 



user$fun 



PUSHH 

LHLD 1 

MVI L, useroffset * 3 

XTHL 

RET 



;place HL reg. pair on stack 

;load address of jump vector 1 (WBOOT) into HL 

;get offset of 90 (30*3) to L 

;exchange HL with top of stack 

ijump to new HL pointer location of routine 



First, the main program loads the user function number (2) into the A register. To 
call a user function, place the required input parameter, the user function number, in the 
A register. If a subfunction is going to be called, like in user function 4 (8502 BIOS), the 
input parameter for the subfunction number must be placed in L. 

The second instruction in the main routine is a CALL to the subroutine user$fun. 
However, in this example of die keyscan user function, the returned value B is -1 if 
no key is pressed. If this is the case, B is incremented to zero and the main program 
jumps to waitkey and scans the keyboard again. Otherwise, the rest of the program 
continues processing. 

When the subroutine is called, the first instruction saves the HL register pair, the 
address pointer, on top of the stack. The next instruction loads memory location 1 (low) 
and 2 (high) into register pair HL. The high byte points to the page number that the 
jump vectors are on and the low byte is always 3 (Jump #1 the warm boot vector). Next 
the jump number times 3 is loaded into the low byte (L) of register pair HL. This adds the 
offset of 90 memory locations to base address of the CP/M BIOS jump table, which now 
points to jump number 30, USERF. 
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u 



u 



The XTHL instruction exchanges the HL register pair with the top of the stack. 
This places the computed address on the top of the stack and the entry values of HL 
back in HL. When the RETum instruction is reached by the Z80, program control is 
therefore passed to the USERF vector, entry 30 in the CP/M BIOS jump table. When 
the function has completed, control returns to the instruction inmiediately following the 
CALL User$Fun instruction (INR B). 

In order for the routines to be called successfiilly, the proper required input 
parameters must be placed in the appropriate registers. The user function number must 
be placed in the A register, the subfunction number is placed in L, if any. Additional 
inputs must be placed in the correct register or variable prior to calling the user function. 

The above example calls user function 2, the keyscan function. To call any other ^ 

user fiinction, load the subfunction number into the A register. To call a subfunction, 
load the L register with a subfunction number on the beginning of the main (calling) j j 

program as follows: uj 

MVI L, subfim 

The way this program is written, the value in L, which you will load at the beginning jj 

of the program with the above instruction, is placed back in L from the stack when the 
XTHL is reached at the end of the subroutine. Use this example as a template when 
calling other subfunctions. Make sure the proper inputs are present in the correct I f 

locations prior to calling the user function. U 

CALLING A CP/M BIOS ROUTINE j 

Making a direct BIOS call is different from calling a user function. User function calls 

always enter jump number 30 in the CP/M BIOS jump table. A direct BIOS call enters j^ 

any of the first 30 (0-29) jump vectors. These are the input and output routines that are j 

a part of any CP/M system on any microcomputer. The standard method of calling a 

CP/M BIOS routine is via BIOS function 50. This function handles the banking of the 

two 64K RAM banks in the C128. j j 

You could call a CP/M BIOS routine similar to the first example, but there is a lj 

limitation. With the user function call method, you are only able to call BIOS routines 
that reside in RAM bank 1. The TPA resides in bank 1, while the Z80 function code is , 

stored in RAM bank 0. If you try to call a direct BIOS routine in bank 0, the system will \ 

crash because bank 1 is in context. This is why it is important to make direct 
CP/M BIOS calls through user function 50. Refer to the Digital Research CP/M Plus 
documentation for more details on user function 50. 1 

Here's a program example that illustrates how to call a CP/M BIOS function. 1_ 

main 

MVI C,50 ;store function no. 50 in reg. C j j 

LXI D,bios$pb ;load immediate a 16 bit pointer in DE (J 

CALL 5 ;standard BIOS call 



u 



n 
1 1 



J I 
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! i 



! i 



11 



Rest of Program 



RET 

bios$pb: ;BIOS variable table 

db FUNNUM ;BIOS function no. variable 

db AREG ;temporary A reg. storage 

dw BCREG ;temp EC reg. pair storage 

dw DEREG ;temp DE reg. pair storage 

dw HLREG ;temp HL reg. pair storage 

The Hrst instruction in the main routine stores the function number SO in the C 
register. The system expects the input parameter C to be the BIOS function number. The 
next instruction loads die address of the BIOS variable table bios$pb into register pair 
DE. The third instruction calls BDOS function 50 through the call BDOS vector, the 
standard BIOS vector through which all direct BIOS functions are called. BDOS 
function 50 manipulates the banking in and out of RAM banks and 1. This is the 
recommended way of directly calling a CP/M BIOS function over that of the first 
example which is designed primarily for calling user functions. 

The variable table "bios$pb" contains the necessary input parameters required for 
BDOS function 50. The "db" 's stand for a byte of storage (like .byte in 8502) while the 
"dw" 's stand for a 16 bit word (like .word in 8502). 

This appendix is the only section of the book that crosses the Z80 programming 
barrier. It at least points you in the right direction and gives you the "hooks" into the 
machine level routines of the CP/M system. For more detailed Z80 programming 
information see the "Suggestions for Further Reading" at the back of the book. For 
more detailed CP/M information, refer to the Digital Research CP/M Plus documentation. 

MFM DISK FORMATS 

The abbreviation MFM stands for Modified Frequency Modulation. This type of disk 
format is variable and programmable according to the specifications of the particular 
computer manufacturer. 

The Commodore 128 CP/M system supports four standard MFM disk formats. These 
four formats constitute the majority of CP/M software formats available on the market. 
This does not mean that the Commodore 128 CP/M system can read every single CP/M 
disk format in the universe; however, the majority of available CP/M software can run 
on the Commodore 128, if the particular application is not hardware dependant. 

The four major formats that are supported are as follows: 

a) Epson QXIO (double sided) 
al) Epson QXIO (double sided) 

b) IBM-8 (single sided) 
bl) IBM-8 (double sided) 

c) KayPro IV (double sided) 

d) KayPro II (single sided) 

e) Osborne (single sided) 
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Each of these formats is compatible with the Commodore 128 CP/M system. At 
the present time, the system camiot format these disk types and successfully use them on 
the host system, but they can be used on the C128 system. This portion of the system 
is still in development. 

The following table lists the parameters that these disk formats are looking for 
when reading third party CP/M software. 



Li 





a 


Ma 

b 


nufacture 
c 


rs 
d 


e 


al 


bl 


Disk Type 


DSDD 


SSDD 


DSDD 


SSDD 


SSDD 


DSDD 


DSDD 


Starting pos. (t/s) 


2/1 


1/1 


0/10 


1/0 


3/1 


2/1 


1/1 


Sector size (bytes) 


256 


512 


512 


512 


1024 


512 


512 


Number of sec/trk 


32 


8 


10 


10 


5 


20 


8 


Number of tracks 


40 


40 


80 


40 


40 


40 


80 


Block alloc size 


2048 


1024 


2048 


1024 


1024 


2048 


2048 


# of dir entries 


128 


64 


128 


64 


64 


128 


64 


# of resvd tracks 


2 


1 


1 


1 


3 


2 


1 



SS = single sided 
DS = double sided 
DD = double density 

MFM Disk Format Table 



u 



u 



u 



U 




NOTE: Epson (a) labels sector numbers 1 through 16. The other Epson 
QXIO format (al) labels sectors from 1 to 10. Both the top and bottom of 
the disk are labeled the same way. 

IBM (b) labels sector numbers 1 through 8. Both the top and 
bottom of the disk are labeled the same way. 

KayPro IV and KayPro II (c and d) label sector numbers through 
9 on top and 10 through 19 on the bottom. 



These values are taken from the MFM table. The vector at $FD46 holds the 
pointer to the start of the table labeled MFM$table. In the current system, these are the 
formats that are read and write compatible on the Commodore 128 CP/M Plus system. 

The following is a listing of the MFM format table: 



1 i 
1 1 

1 i 
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i i 

i 1 


db 
db 
dw 
dpb 


S256*2 + (16*2-«) + l 

MFM + S2S6 + TypeO + CO + SI 



256,32,40,2048,128,2 


; 256 byte sect, 16 sect/trk 
; DSDD 

;start on track 2 sect 1 (2 ale) 
; sect# 1 to 16 


1-^ 

ii 


db 
db 


16 

'Epson QXIO' 


;1 Epson QXIO 


i 1 
p 


db 
db 
db 
dw 
dpb 


80h + SS12*2 + (10*2-8) +1 

S256*2 

MFM + S512 + TypeO + CO + SI 



512,20,40,2048,128,2 


;512 byte sect, 10 sect/trk 
;track is 256 bytes/sector 
; DSDD 

;start on track 2 sect 1 (2 ale) 
;sect# 1 to 10 


n 


db 
db 


10 

'Epson QXIO' 


;(top and bottom numbered the same) 

;2 


n 

1 i 

n 


db 
db 
dw 
dpb 


S512*2 + (8*2-8) + 1 

MFM + S512 + Type2 + CO + SI 



512,8,40,1024,64,1 


;512 byte sect 8 sect/trk 

; SSDD 

;start on track 1 sector 1 (2 ale) 

;sect# 1 to 8 


1 


db 
db 


8 

' IBM-8 SS' 


;3 


1 ; 

1 I 

1 


db 
db 
dw 
dpb 


S512*2 + (8*2-8) + 1 

MFM + S512 + Type2 + CO + SI 



512,8,80,2048,64,1 


;512 byte sect 8 sect/trk 

; DSDD 

; start on track 1 sector 1 (1 ale) 

; sect# 1 to 8 


[ 
n 


db 
db 


8 

' IBM-8 DS' 


; (top and bottom numbered the same) 

;4 


', ! 

"I 
jl 


db 
db 
dw 
dpb 


S512*2 + (10*2-8) + 

MFM + S512 + Typel + CI + SO 



512,10,80,2048,128,1 


; 512 byte sector, 10 sect/trk 
; DSDD 

; start on track sector 10 (2 ale) 
; sect# to 9 on top (even tracks) 


1 I 
1 1 


db 
db 


10 
'KayPro IV' 


; sect# 10 to 19 on bottom (odd tracks) 

;5 


M 

n 
1 i 


db 
db 
dw 
dpb 


S512*2 + (10*2-8) + 

MFM + S512 + TypeO + CI + SO 



512,10,40,1024,64,1 


; 512 byte sect, 10 sect/trk 
; SSDD 

; start on track 1 sector (4 ale) 
; sect# to 9 


n 


db 

db 


10 
'KayPro H' 


;6 



MFM Format Table 
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db 


S1024*2 + (5*2-8) + 1 




1024 byte sect, 5 sect/trk 


db 


MFM + S1024 + TypeO 


+ C0+S1 


SSDD 


dw 







start on track 3 sector 1 (2 ale) 


dpb 


1024,5,40,1024,64,3 




sect# 1 to 5 


db 


5 






db 


'Osborne DD' 




7 



MFM Format Table (continued) 



u 



u 






! ( 

u 
u 



u 
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n 



APPENDIX K 

PART III 

THE CP/M SYSTEM MEMORY MAP 



} I The following pages contain the Z80 CP/M memory map for the Commodore 128. 

The memory map includes all the key CP/M locations, vectors and variable tables. 
^ Use it as a guide through the Z80 CP/M system within the Commodore 128. 

1 1 The CP/M memory map is available as a disk file "CXEQU.LIB" on the disk 

' ^ that comes with the computer. 

n 



n 

! I 



I i 
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$*m.cRO 

false 

true 

banked 

EXTSyS 

pre$release 



equ 
equ 
equ 
equ 
equ 



; start at Jan 1,1978 
dt$hx$yr equ 

1985 
dateShex equ 



not false 

true 

false ; use external system as disk and char I/O 

false 

78 79 80 81 82 83 84 
365+365+366+365+365+365+366 

123456789 10 11 12 
dt$hxSyr+31+28+31+30+31+30+31+31+30+31+30+6 



u 



date 



macro 

db 

endm 



'6 Dec 85' 



boot menory map (bank only) 



bios02 


equ 


3000h 






blockSbuffer 


equ 


3400h 


uses 2F 




bootSparm 


equ 


3C00h 


uses about 256 bytes 


; bank low nvemory map 








HOM 


equ 


OOOOh 






VICSoolor 


equ 


lOOOh 


I/O page only (IO$0 selected) 


sysSkey$area 


equ 


lOOOh 


3 256 byte blocks (allow 4) 


screen540 


equ 


1400h 


2 X 80 X 25 = 4000 


BANK$parm$blk 


equ 


2400h 


allow C 


.5K of parameters 


BIOS8502 


equ 


2600h 


1.5K 




VIC$ screen 


equ 


2C00h 


IK 




ccp$buffer 


equ 


3000h 


0c80h 


allow 4K) 


bankO$free 


equ 


4000h 


start of free area in bank 


; mapped I/O locaticais 








VIC 


equ 


ODOOOh 






SID 


equ 


0D400h 






MMU 


equ 


ODSOOh 






DS8563 


equ 


0D600h 




8563 


VIC$C$H 


equ 


ODSOOh 




(manory mapped only in lOSO) 


VICSCSL 


equ 


OlOOOh 




(memory and i/o mapped in IO$Q) 


CIAl 


equ 


ODCOOh 




6526 


CIA2 


equ 


ODDOOh 




6526 


USART 


equ 


ODEOOh 




6551 (extm card) 


RAM$dsk$base 


equ 


ODFOOh 




8726 








int$block 


equ 


OPCOOh 


; mode 2 


interrupt pointers (to FDFDh) 


pann$block 


equ 


OFDOOh 


; system 


parameters 


(a buffer 


equ 


OFEOOh 
OEFOOh 


; disk bi 
; to OFFl 


offer (256 bytes) 
JFh used by 8502 


; the following are C128 systan 


equates 




enableSz80 


equ 


OFFDOh 




• 8502 code 


retumSz80 


equ 


OFEDQl 






enable$6502 


equ 


OFFEOh 




• Z80 code 


retum$6502 


equ 


OFFEKh 




; 1st byte used as Intterrupt poi 


vic$cnd 


equ 


panri$blo 


ck+1 


;; bios8502 ccitimand byte 


vicSdrv 


equ 


vic$crad+ 


1 


; bios8502 drive (bit set, drv 


vic$trk 


equ 


vic$drv+ 


1 


; ; bios8502 track # 



u 
U 
U 
U 






u 
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n 



1 \ 



n 

n 



n 



vic$sect 

vic$count 

vic$data 

cur$drv 

fast 



equ 
equ 
egu 
equ 
equ 



keyStbl equ 

funStbl equ 
oolor$tbl$ptr equ 

fun$offset equ 

sound$l equ 

sound$2 equ 

sound$3 equ 



<?trk 
@dina 



equ 
equ 



vic$trk+l 

vic$sect+l 

vic$count+l 

vic$data+l 

cur$drv+l 

fast+1 

keyStbl+2 

fun$tbl+2 

color$tbl$ptr+2 

fun$offset+l 

sound$l+2 

soundS2+2 

sound$3+2 
@trk+2 



; below here ncjt used by ROM 



^sect 

@cnt 

@cbnk 

(aadrv 
@rdrv 
ccpScount 

stat$enable 



equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 



emulation$adr equ 

usart$adr equ 
; CXIO equates 

int$hl equ 

int$stack equ 

user$hl$tsnip equ 

hlStanp equ 

de$temp equ 

a$tenip equ 

souroe$bnk equ 

dest$bnk equ 

MEM$tbl$ptr equ 
; 1st release end 

prt$oonv$l equ 

prtSoonv$2 equ 

key$EX$function equ 

}&cD$canfig equ 



RS232$status equ 



@dnia+2 

@ sect+2 

S'cnt+l 

@cbnk+l 

edbnk+l 

dadrv+l 

@rdrv+l 

ocp$count+l 



stat$enable+l 
e[nulation$adr+2 

usart$adr+2 
intShl+2+20 
int$stack 
user$hlSt€nipf2 

hl$te!npf2 

de$taii>+2 

a$ten5ri-l 

source$bnk+l 

dest$bnk+l 

MFM$tbl$ptn'2 
prt$c»nv$l+2 
prt$a3nv$2+2 
key$KXSfunction+2 



XXDSoonfig+1 



3nnit$data 
recv$data 



equ 
equ 



RS232$status+l 
3<mitSdata+l 



bios8502 sector # 

bios8502 sector count 

bios8502 data byte to/f ran 

current disk installed to Vir. drive 

bit set, drv is fast. ect. 

pointer to keyboard table 
pointer to function table 
pointer to logical color table 
function # to be prepormed 
unused 



current track number 
current DMA address 



current sector nuniber 
record count for multisector transfer 
bank for processor operaticxis 
bank for DMA c^jeraticms 
currently selected disk drive 
controller relative disk drive 
number of records in the CCP 
status line enable 
7 kjtord, key ccdes(l), functicns(O) 
6 40 column tracking on(0), off(l) 
disk Stat, enableU), disable(O) 
address of current emulaticxi 
pointer to USART (6551) register 

interrupt HL hold location 
currently cmly 5*2 used 
user function HL hold location 
ndsc temp storage {used by VECTOR) 
misc temp storage (used by VECTOR) 
misc tenp storage (used by VECTOR) 
inter bank move source bank # 
inter bank move dest bank # 
pointer to MEM table 



bit 
bit 
bit 



= no parity 
= mark/space 
= space/even 



1 = parity 
1 = odd/even 
1 = mark/odd 



bit 1 
bit 



1 stop bit 1 = 2 stop bits 
7 data bits 1 = 8 data bits 



bit 7, l=send data, 0=no data 

bit 6, l=sending data 

bit 5, l=recv que active 

bit 4, l=parity error 

bit 3, l=iraraing error 

bit 2, l=recv over run (no used) 

bit 1, l=receiving data 

bit 0, l=Data byte ready 

data byte to send 
received data byte 



; The following equates are used by the interrupt driven keyboard handler 
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int$rate 



equ 



recvSdata+1 



1st byte is a pointer into table, 2nd to 12th byte represent 
the keyboards current state (active low), NOTE: only 
current if key$buf fer is not full 



key$scan$tbl equ int$rate+l 

; keyboard roll over buffer 

keySbuf$size equ 8*2 

keySgetSptr equ 

key$put$ptr equ 

keySbuffer equ 



key$scan$tbl+12 

keySget$ptr+2 

keySputSptr+2 



; must be an even number of bytes 



software UART recv buffer 



RxD$buf$size equ 

RxDSbuf$count equ 

RxD$buf$put equ 

PxD$buf$get equ 

RXD$buffer equ 

tick$vol equ 

; equ 



64 

keySbuffer+keySbufSsize 

RxD$bufScount+l 

RxDSbuf$put+l 

RxD$buf$get+l 

RxD$buffer+R3iD$buf$size 

tick$vol+l 



lOTSvector 


equ 


OFDFDh ; 


■ ccxitains a JMP int$handler 






; (in caimon) 


;=> 40 coluirai 


misc 


parm 


tenpSl 


equ 


BANK$parm$blk 




(a of f 40 


equ 


taip$l+2 ; 




cur$offset 


equ 


@ off 40 ; 




oldSoffset 


equ 


(aoff40+2 




prt$flg 


equ 


old$offset+l ; 




flash$pos 


equ 


prt$flg+l 




•==> 40 column position and color storage 


paint$size 


equ 


flash$pos+2 ; 


; 


char$adr$40 


equ 


paint$size+l ; 


; 


char$col$40 


equ 


char$adr$40+2 


; 


char$rowS40 


equ 


char$col$40+l ; 


; 


attr$40 


equ 


char $row$4 0+1 ; 


; 


bg$color$40 


equ 


attrS40+l ; 


; 


bd$color$40 


equ 


bg?color$40+l ; 


; 


rev$40 


equ 


bdScolor$40+l ; 


'■ 


;=> 80 column position and color storage 


charSadr 


equ 


revS40+l 




charScol 


equ 


char$adr+2 ; 




charSrow 


equ 


char$col+l ; 




current$atr 


equ 


char$row+l ; 




bg$color$80 


equ 


currentSatr+1 ; 




char$color$80 


equ 


bgScolor?80+l ; 




; KM uses localtions above this point 


;=> Bnulation paramsters 


parm$base 


equ 


char$color$80+l 


parmSarea$80 


equ 


parm$base+2 


; 


ds 


2 ; 80 column exec$adr 


t 


ds 


1 ; 80 column row # 


parm$area$40 


equ 


parm$areaS80+3 


; 


ds 


2 ; 40 column exec$adr 


; 


ds 


1 ; 40 column row # 


bufferS80$col 


equ 


parm$areaS 40+3 





=> C3aO parameters 

int$count not used by releases past 10 Oct 85 
int?oount qu buffer$80$ool+40*2 ; one added every l/60th sec 
key$buf ei i intScount+1 



'J 



u 



u 



u 



u 



u 
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; 1 



I I 



;=> CXKEXS parameters 

keySdown?tbl equ keySbuf+1 ; not used any more (int code) 

;;;;; free space above, new interrupt driven code does not require this space 
; controlSkeys equ keySdown$tbl+ll*2 ; byte, not used any more (int code) 



ocnimodoreSmode equ 
msgptr equ 
offset equ 
cur$pos equ 
stringSindex equ 
; 1st release end (3 
sys$freq equ 
; 2nd release end (1 
; equ 



key$dawn$tbl+ll*2 

cciimDdore$mode+l 

rasgptr+2 

offset+1 

curSpos+1 
June 85) 

stringSindex+1 
Aug 85) 

sys$freq+l 



-l=50Hz, 0=60Hz 



;=> tsnp ROM 

blk$ptrScnt 

loadScount 

ld$blk$ptr 

blkSunld$ptr 

block$size 

block$end 

block$ptrs 

infoSbuffer 

ext$nuni 

retry 

bootSstack 



boot 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 

equ 
equ 
equ 
equ 



data storage 
32 

boot$parm 
load$count+2 
ld$blk$ptr+2 
blk$unld$ptr+2 
block$size+l 
blockSend+2 



number of 128 byte blocks to load 
current sector dma pointer 
read memory block (lk,2K) pointer 
block size (1K=32 or 2K=64) 
allow 48K cpm.sys to load 

, end of block load buffer (+1K or +2K) 

block$ptrs+blkSptr$cnt 

; CPM3.sys load adr's and counts 

infoSbuffer+12 ; CMG.SYS current ext # 

extSnum+1 

retry+1+64 ; allow 64 bytes of stack 

bootSstack 



=> special equates used by CXKEy 



special 

SPSexit 

SF$insert 

SF$delete 

aljteStoggle 

altSkey 

SF?left 

lf$arrow 

SFSright 

rt$arrow 



equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 



00010111b 

00 Ih 

028h 

02Bh 

03Dh 

050h 

055h 

055h 

056h 

056h 



RETURN KEy 
PLUS KEY 
MINUS KEY 
cammodore key 
alterant key 
left arrow key 
left arrow key 
right arrow key 
right arrow key 



buff?large 
buff$small 
buffSpos 



equ 
equ 
equ 



25 

7 

7 



;=> External RS232 interface controls 

rxdS6551 equ USAROM-O 

txd$6551 equ USARIM-O 

status$6551 equ USAR34-1 

reset$6551 equ USARIH-1 

ccmnand$6551 equ USARr4-2 

control$6551 equ USAR3M-3 

txrdy equ lOh 

rxrdy equ 08h 

cndSinit equ Obh 

cntrSinit$19200 equ IFh 

cntrSinit$9600 equ ISi 

cntr$init$600 equ 01 7h 



read 

write 

read 

write 

read/write 

read/write 



no parity, enable txd + rxd, interrupts off 

1 step, 8 bits, 19200 baud 

1 stop, 8 bits, 9600 baud (internal) 

600 baud 



;=> memory management loactions 



mmuSstart 

canf$reg 

confSreg$l 

conf5reg$2 

conf$reg$3 

ccaif$reg$4 

nodeSreg 



equ 

equ 
equ 
equ 
equ 
equ 
equ 



MMU 

^MU 

MMU+l 
NMU+2 
MMU+3 
NMU+4 
MMU+5 



3eh 
3fh 
7fh 
3eh 
7eh 
blh 
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ramSreg 


equ 


^M^Jf6 


; Obh 16K t<^ Caiman 


page$0$l 


equ 


MMU+7 


; OOh 


page$OSh 


equ 


NMW-8 


; Olh 


page$l$l 


equ 


IM3+9 


; Olh 


pageSlSh 


equ 


mu+10 


; Olh 


mmuSversion 


equ 


MMU+ll 


; ??h 


aiable$C64 


equ 


11110001b 


; FS=0 


zSOSoff 


equ 


10110001b 


; value to be vnrite 1 


z80$on 


equ 


10110000b 




fast$rd$en 


equ 


Z80$on+a 


; fast serial read 


fast$wr$en 


equ 


Z805on+8 


; fast serial write 


ooninon$4K 


equ 


09h 


; top 4K cannon 


ccmmon$8K 


equ 


Oah 


; top 8K caraion 


c»nmonS16K 


equ 


Obh 


; top 16K canmon 


;=> preccaifiguration maps 




forceSm^ 


equ 


OffOOh 




bankSO 


equ 


OffOlh 


; 3fh 


bank$l 


equ 


0ff02h 


; 7fh 


io 


equ 


0ff03h 


; 3eh 


io$0 


equ 


0ff03h 


; 3eh 


io$l 


equ 


0ff04h 


; 7eh 


,==> 80 column display equates 




DS$inclex$reg 


equ 


DS8563 




DS$status$reg 


equ 


DS8563 




ES$data$reg 


equ 


DS8563+1 




;=> register pointers 




DS5cursor$high 


equ 


14 




DS$cursor$lcw 


equ 


15 




DS$rw5ptr$high 


equ 


18 




DSSrwSptrSlow 


equ 


19 




DS$rw$data 


equ 


31 




DS$color 


equ 


26 




;=> status bits 






D6$ready 


equ 


80h 




D6$ltSpen 


equ 


40h 




;==> display memory layout (16K) 


0-3fffh 


D6$screen 


equ 


OOOOh 




DS$attribute 


equ 


0800h 




DS$char$def 


equ 


2000h 




;==> VIC equates 






; vie colors 









u 
u 



u 



u 



u 



black 

white 

red 

cyan 

purple 

green 

blue 

yellcw 

orange 

brown 

lt$red 

dark$grey 

nedSgray 

ItSgreen 

lt$blue 

lt$grey 



equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 





1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 



BM$status 
bit 7 

6 

5 
note: bits 

4 

3-0 



equ RAM$dsk$base 
Interrupt pending if 1 
Transfer catplete if 1 
Block verify error if 1 
5-7 are cleared when read 
128K if 0, 512K if 1 
Version # 



;read only register 



u 

u 

y 
y 

u 

u 



n 
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RM$ccininand 
; bit 7 
6 
5 



4 

3,2 

1,0 



RM$128$low 

bits 



equ PAM$clsk$base+l ;r/w 

execute per current oonfig. if set 

reserved 

enable auto reload if set (restores all register to 

value before camnand was done, else point to 

next byte to read/write. ) 
disable FFOO decode if set (do operation after canmand writen) 
reserved 

00 = transfer C128 — > Ram Disk 

01 = Transfer C128 < — Ram Disk 

10 = swap C128 <-> Ram Disk 

11 = Verify CI 28 = Ram Disk 



equ RAM$dsk$base+2 
to 7 of C128 address 



;r/w 



RM$128Sraid equ RAM?dsk$base+3 ;r/w 
; bits 8 to 15 of the C128 address 

t 

RM$extSlow equ RftMSdsk$base+4 ;r/w 
; bits to 7 of Ram Disk address 

RM$ext$mid equ RAM$dsk$base+5 ;r/w 
; bits 8 to 15 of Ram Disk address 

RM5ext$hi equ RflMSdskSbase+6 ;r/w 

; bit 16 of Ram Disk address if 128K version 

; bits 16 to 18 of Ram Disk address if 512K version 

, 

RM$count$low equ RflM$dsk$base+7 ;r/w 

; low byte transfer count (bits 0-7) 

RM$count$hi equ RflM$dsk$base+8 ;r/w 
; hi byte transfer count (bits 8-15) 

RM$intr$mask equ RAMSdsk$base+9 ;r/w 

; bit 7 l=enable chip interrupts 

; 6 l=enable end of block interrupts 

; 5 l=enable verify error interrupts 

RM$control equ RfiM$dsk$base+10 ;r/w 

; bit 7,6 00 Incranent both acMresses 

; 01 Fix expansion address 

; 10 Fix C128 address 

; 11 Fix Ijoth addresses 



(default) 



=> CIA equates 



Data$a 

Data$b 

Data$dir$a 

Data$dirSb 

timer$aSlow 

tiraer$a$high 

timerSbSlow 

timer$b$high 

todSsecSeO 

tad$sec 

tod$min 

tod$hrs 

syncSdata 

int?ctrl 

cia$ctrl$a 

cia?otrl$b 

CIA$hours 



equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 



OOh 
Olh 
02h 
03h 
04h 
05h 
06h 
07h 
08h 
09h 
Oah 
Obh 
Och 
Odh 
Oeh 
Ofh 
CIAl+tod?hrs 



keySrow 



equ 



CIA1+Data$a 



output 
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key$ool 
VICSkey$row 



data$hi 
dataSlcw 

lf$shiftSkey 
rt$shift$key 
cx3itinciclore$key 
control$key 

type$lciwer 
type$upper 
type$shift 
type$cntrl 
type$field 

tnkl equ 
pageO equ 
pagel equ 

MMU$tblSM 
db 
db 
db 
endm 



equ 
equ 



equ 
equ 

equ 
equ 
equ 
equ 

equ 
equ 
equ 
equ 
equ 

1 

1 



CIA1+Data$b 
0d02fh 



4 



80h 
lOh 
20h 
04h 


1 
2 
3 
00000011b 



input 
output 



BS232 data line HI 
RS232 data line LCM 



macro 

3fh,3fh,7fh,3eh,7eh 
zSOSon , ccninan$ 8K 
pageO , bnkl , pagel , bnkl 



RCM functions 



ccnfig reg's 
mode & msn 
page reg's 



u 



u 



ij 



u 



I ) 



u 



TJMP 



macro 
rst 2 
endm 



X 

1 db X 



TCALL 



ROMP 



RCALL 



ra$40 



macro x 

mvi l,x ! rst 4 

endm 



necro 
rst 3 
endm 



! db X 



macro x 

mvi l,x ! rst 5 

endm 



IR$wr$char 

5R$cursor$pos 

IK$cursor$up 

PR$cursor$down 

ER$cur sor $ left 

ER$cursor$rt 

PRSdo$cr 

FRSCEL 

FR$CES 

FR$charSins 

FRJcharSdel 

FR$line$ins 

fR$line$del 

FR$color 

PR$attr 

FRSrd$chr$atr 

FRSvnr$chr$atr 

ER$rdScolor 
;FR$v(r$color 



equ 

equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 

equ 

equ 
equ 
equ 



OOh 
C4h 
08h 
OCh 
lOh 
14h 
ISh 
ICh 
20h 
24h 
28h 
2Ch 
30h 
34h 
38h 
3Ch 

40h 

44h 
48h 
4Ch 



offset to 40 column ROM functions 

D=char auto advance 
B=row, C=oolumn 



B=color 

B=bit to set/clear, Obit value 

in D=rcw, E=ool 

out H=row, L=ool, B=char, Oattr(real) 

in D=row, B=col, B=char, Oattr(real) 

out H=row, D=col 



VI 

u 



u 
u 
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n 



n 



ERStrkSsect 

HRScheck$CBM 

ra$bell 



FR$trkS40 

ER?set?cur$40 

FR$line$paint 

EE$screen$paint 

ER$prt$iiisg?both 

FR?prt$de$both 

ER$updateSit 



FR$ASCIISto?pet 
BR$curSadr$40 
FR$cur$adrS80 
BR$look$color 

FR$blkSfill 
raSblk$inove 
FR?char$inst 



equ 


50h 


equ 


52h 


equ 


54h 


equ 


56h 


equ 


58h 


equ 


5flh 


equ 


5Ch 


equ 


5Eh 


equ 


60h 


equ 


62h 


equ 


64h 


equ 


66h 


equ 


68h 


equ 


6fih 


equ 


6Ch 


equ 


SEh 


equ 


70h 


equ 


72h 


equ 


74h 


equ 


76h 


equ 


78h 


equ 


7Ah 


equ 


7Ch 


equ 


7Eh 



HL passed on the stack 



fixed ROM locations 

R$ciiip$hl$ds equ 

R$write$niemory equ 

R$read$memory equ 

R$set$updateSadr equ 

R$vrait equ 

R$status$color$tbl equ 

R$color$convert5tbl equ 



lOOh-6 

180h+0 
180h+3 
180h+6 
180h+9 

lOOOh-246-16 
lOOOh-230-16 



Disk type byte definition 

bit 7 0=QCR, l=MfM 

if bit 7 is 1 (MEM) 

6 C0=0, Cl=l (side 2 #, to (n/2)-l or n/2 to n-1) 

5,4 00=128, 01=256, 10=512, 11=1024 byte/sector 

3,2,1 disk type (MEM) 

starting sector # ( or 1) 

if bit 7 is (OCR) 

6 unused (set to 0) 

5,4 always 01 (256 byte sectors) 

3,2,1 disk type (GCR) 

TypeO = none, set track and sector as passed 

Typel = C64 type disk 

Type2 = CI 28 type disk 
unused (set to 0) 



MEM 
CO 
CI 
Cl$bit 


equ 
equ 
equ 
equ 


1*128 
0*64 
1*64 
6 


TypeO 


equ 


0*2 


Typel 


equ 


1*2 


Type2 


equ 


2*2 



2nd side start at begining 
2nd side continues fron first 

(MEM) top, bottcm then next track 

CISK* to (34 or 39)) 
(MEM) top (trk even), bottom (trk 1 odd) 

(TRK# to (69 or 79) ) 
(MEM) top TRK# to 39, bottcm TRK# 40 to 79 

(TRK# cm back start at 39 and go to 0) 
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T^pe? equ 



7*2 



(MEM) pass the byte values supplied in "trk 
and "sect 



TypeX equ 



SO 
SI 



equ 
equ 



SI 28 equ 

S256 equ 

S512 equ 

S1024 equ 



dsk$none 

dskSc64 

dsk$cl28 

dirStrack 



7*2 

0*1 
1*1 

0*16 
1*16 
2*16 
3*16 



equ 
equ 
equ 

equ 



6510 connands 



vic$reset 

vic$init 

vic$rd 

vic$vnr 

vicSrdP 

vic$wrF 

vic$test 

vic$query 

vicSprt 

vic$fnnt 

vicSuser$fun 

vicSBMSrd 

vic$RM$wr 



equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 



start at sector 
start at sector 1 



Type0+S256 
Typel+S256 
Type2+S256 

18 



-1 



1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 



control characters 



eon 

bell 

bs 

If 

cr 

xon 

xoff 

esc 



equ 


OOh 


equ 


07h 


equ 


08h 


equ 


Oah 


equ 


Odh 


equ 


llh 


equ 


13h 


equ 


Ibh 



access to any sector on the disk 



C64 disk dir track 



u 
U 

u 



reboot C128 

initilize the bios8502 

read one sector of data (256 bytes) 

write one sector of data 

set-up for fast read (many sectors) 

set-up for fast write 

test current disk in drive 

get start sectors and tsector/trk 

print data character 

format a disk (1541) 

GAM disk read 
RAM disk write 



u 
u 

u 



U 



U 
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COMMODORE 128 SYSTEM SCHEMATICS 

The following eight pages contain the full system schematics for the Commodore 128. 
Each two-page spread represents one full-size engineering schematic sheet. For easier 
readability, the right edge of the left-hand page and the left edge of the right-hand page 
have portions of the schematic that are duplicated. This overlap is provided so you can 
read the circuit diagram from either half of the two-page spread, then move to the 
adjacent page and pick up where you left off from the point where the opposite page 
ends. The arrow at the top of each page provides a frame of reference to mark the 
portion of the diagram that is overlapped. 
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oe-D7 I 
Ae-Ai5 I 



EM AUDIO ( 
P01X [ 
POTY [ 



I MHZ [ 
R/V» C 



ciM,x cine,— 
isBBff^ laitejix 






CASS MTR/P5 

CASS 5EN5E/Pa 

CA5SWRT/P3 

ZMHi 

OIMH? 



B=f 



NOTE : 

X\ LOW END ONLY 
, HIGH END ONLV 

IS 

M C. o-JYTM-O a-. C. 



CRIB 
rN400l 



"?M"'i'-%7tni5 







CTCT 
1D/BB [ 






i|E^ 




CLOSED 
ENABLE 
CASLATO 



OPEN-, 
ITBKIII)! 
ODSEW 
25LKR« 
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aosED 

ENABLE 
CAS LATCH 



OPEU- 
ITSKBUI 
CUISED- 



e/< ■to/' 



+5V 



LORAM ?2 



HIRAM ?^ 



PHAREN 25 



AB I 



CmU 



AM 2 



-fT^' ^ 



110 5EL Ifc 



ROMBANKHrn 



PMBANKi-P IB 



lo-AVV-i 



♦5V1 
.=-003 



3ffl 



5=1 



5SR 

CLK 
DIR 



LOR ''"'P 

CHAREN RgljB 









M53 

MSI 8721 
MSBpLA 
Ull 
128/ 2Sb 

VAI4 




1«7, 



. FR/W 

• AUDIO OUT 

• Dffi-D7 

• Ae-«IS 




4R35 
JlOOA 






<T ZS5 
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TAB-TA15/ 
MAS - MAI I 



-' >-»An PHI 



.32 CLRBMK 



^^ — r^H — V 



-lE)^ 




MICROPROCESSORS, MMU, SID, 
PLA, POWER SUPPLY 
SCHEMATIC 310378 
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CNI3 
LED 



R42 
180 Jl. 



R3Z 
ISOA- 




^ LOW EMO ONLY 
/^ HIOH END ONLV 



I/O CONNECTOR 



n 



I/O — Control Ports, Keyboard, 
User Port, Serial Port, Cassette Port 
SC SCHEMATIC 310378 
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GLOSSARY 



This glossary provides brief definitions of frequently used computing terms. 



Acoustic Coupler or Acoustic Modem: A device that converts digital signals to 
audible tones for transmission over telephone lines. Speed is limited to about 1200 
P| baud, or bits per second (bps). Compare Direct Connect Modem. 

I i Address: The label or number identifying the register or memory location where a unit 

of information is stored. 
/-> Alplianumeric: Letters, numbers and special symbols found on the keyboard, exclud- 

j j ing graphic characters. 

ALU: Arithmetic Logic Unit. The part of a Central Processing Unit (CPU) where 
mathematical operations are performed. 
j 1 Animation: The use of computer instructions to simulate motion of an object on the 

' i screen through gradual, progressive movements. 

Array: A data storage structure in which a series of related constants or variables is stored 
n in consecutive memory locations. Each constant or variable contained in an array 

) } is referred to as an element. An element is accessed using a subscript. See 

Subscript. 
j-^ ASCII: Acronym for American Standard Code for Information Interchange, which is a 

I j seven-bit code used to represent alphanumeric characters. It is a useful communi- 

cation code for such things as sending information from a keyboard to the 
computer, and from one computer to another. See Character String Code. 
n Assembler: A program that translates assembly language instructions into machine 

! I language instructions. 

Assembly Language: A machine-oriented language in which mnemonics are used to 
r-i represent each machine language instruction. Each CPU has its own specific 

I assembly language. See CPU and Machine Language. 

Assignment Statement: A BASIC statement that sets a variable, constant or array 
element to a specific numeric or string value. 
! I Asynchronous Transmission: A conununication scheme in which data characters are 

i' ' sent at time intervals, independent of the system clock. Limits phone line trans- 

mission to about 2400 baud (bps). See Synchronous Transmission. 
~! Attack: The rate at which the volume of a musical note rises from zero to peak volume. 

I Background Color: The color of the portion of the screen that the characters are 

placed upon. 

^ 731 
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BASIC: Acronym for Beginner's All-purpose Symbolic Instruction Code. ^ 

Baud: A unit of serial-data transmission speed. The term was originally used for 

measuring telegraph transmission speed. Three hundred baud is approximately ) [ 

equal to a transmission speed of 30 bytes, or characters, per second. Li 

Binary: A base-2 number system. All numbers are represented as a sequence of Os and 

Is. 
Bit: The abbreviation for Binary diglT. A bit is the smallest unit in a computer's 

memory. Each binary digit can have one of two values, or 1 . A bit is referred to 

as set or "on" if it equals 1. A bit is clear or "off if it equals 0. 
Bit Control: A means of transmitting serial data in which each bit has a significant 

meaning and a single character is surrounded with start and stop bits. 
Bit Map Mode: An advanced graphic mode in the Commodore 128 in which you can 

control every pixel on the screen. I 

Border Color: The color of the edges around the screen. [J, 

Branch: To jump to a section of a program and execute it. GOTO and GOSUB are 

examples of BASIC branch instructions. , 

Bubble Memory: A relatively new type of computer memory, it uses tiny magnetic I 

"pockets" or "bubbles" to store data. 
Burst Mode: A special high-speed mode of communication between a 1571 disk drive 

and a C128 computer, in which information is transmitted at many times the speed \ { 

of the 1541 Disk Drive. U 

Bus: Parallel or serial lines used to transfer signals between devices. Computers are 

often described by their bus structure (i.e., S-100-bus computers, etc.). i / 

Bus Network: A system in which all stations or computer devices communicate by 11 

using a common distribution channel or bus. 
Byte: A group of 8 bits that make up the smallest unit of addressable storage in a 

computer. Each memory location in the Commodore 128 contains 1 byte of 

information. One byte is the unit of storage needed to represent one character in 

memory. See Bit. 
Carrier Frequency: A constant signal transmitted between communicating devices | I 

that is modulated to encode binary information. U 

Character: Any symbol on the computer keyboard that is printed on the screen. 

Characters include numbers, letters, punctuation and graphic symbols. , , 

Character Memory: The area in Commodore 128's memory that stores the encoded | 

character patterns that are displayed on the screen. 
Character Set: A group of related characters. The Conmiodore 128 character sets 

consist of upper case letters, lower case letters and graphic characters. j I 

Character String Code: The numeric value assigned to represent a Commodore 128 ij, 

character in the computer's memory. 
Chip: A miniature electronic circuit that performs a computer operation such as i i 

graphics, sound and input/output. I I 

Clock: The timing circuit for a microprocessor. 
Clocking: A technique used to synchronize the sending and receiving of data that is 

modulated to encode binary information. 
Coaxial Cable: A transmission medium, usually employed in local networks. 
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Collision Detection: Determination of collision between two or more sprites or 

between sprites and data. 
Color Memory: The area in the Commodore 128's memory that controls the color of 

each location in screen memory. 
Command:\A BASIC instruction used in direct mode to perform an action. See Direct 

Mode. / 
Compiler: A program that translates a high-level language, such as BASIC, into 

machineManguage . 
Composite Monitor: A device used to provide the C128 40-column video display. 
Computer: An electronic, digital device that inputs, processes, and outputs information. 
Condition: Expression(s) between the words IF and THEN, in an IF . . . THEN 

statement, evaluated as either true or false. The conditional IF . . . THEN 

statement gives the computer the ability to make decisions. 
Coordinate: A single point on a grid having vertical (Y) and horizontal (X) values. 
Counter: A variable used to keep track of the number of times an event has occurred in 

a program. 
CPU: Acronym for Central Processing Unit, the part of the computer containing the 

circuits that control and perform the execution of computer instructions. 
Crunch: To minimize the amount of computer memory used to store a program. 
Cursor: The flashing square that marks the current location on the screen. 
Data: Numbers, letters or symbols that are input into the computer and are to be 

processed. 
Database: A large amount of related data stored in a well-organized manner. A 

database management system is a program that allows access to the information. 
Data Linl< Layer: A logical portion of data communications control that mainly 

ensures that communication between adjacent devices is error-free. 
Data Packet: A means of transmitting serial data in an efficient package that includes 

an error-checking sequence. 
Data Rate or Data Transfer Rate: The speed at which data is sent to a receiving 

computer — ^given in baud, or bits per second (bps). 
Datassette: A device used to store programs and data files sequentially on tape. 
Debug: To correct errors in a program. 
Decay: The rate at which the volume of a musical note decreases from its peak value to 

a midrange volume called the sustain level. See Sustain. 
Decrement: To decrease an index variable or counter by a specific value. 
Dedicated Line or Leased Line: A special telephone line arrangement supplied by 

the telephone company, and requked by certain computers or terminals, whereby 

the connection is always established. 
Delay Loop: An empty FOR . . . NEXT loop that slows the execution of a 

program. 
Dial-Up Line: The normal switched telephone line that can be used as a transmission 

medium for data communications. 
Digital: Of or relating to the technology of computers and data communications 

where all information is encoded as bits of Is or Os that represent on or off 

states. 
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Dimension: The property of an array that specifies the size and direction along an axis 
in which the array elements are stored. For example, a two-dimensional array has 
an X-axis for rows and a Y-axis for columns. See Array. ) 

Direct Connect Modem: A device that converts digital signals from a computer into 
electronic impulses for transmission over telephone lines. Contrast with Acoustic 
Coupler. 

Direct Mode: The mode of operation that executes BASIC commands immediately after 
the RETU RN key is pressed. Also called Immediate Mode. See Command. 

Disable: To turn off a bit, byte or specific operation of the computer. 

Disi< Drive: A random access, mass-storage device that saves and loads files to and 
from a floppy diskette. 

Disic Operating System: A program used to transfer information to and from a disk. 
Often referred to as a DOS. 

Duration: The length of time a musical note is played. 

Electronic Mail, or E-Mail: A communications service for computer users in which 
textual messages are sent to a central computer, or electronic "mailbox," and 
later retrieved by the addressee. 

Enable: To turn on a bit, byte or specific operation of the computer. 

Envelope Generator: Portion of the Commodore 128 that produces specific wave- 
forms (sawtooth, triangle, pulse width and noise) for musical notes. See Waveform. j { 

EPROM: A PROM that can be erased by the user, usually by exposing it to ultraviolet 
light. Abbreviation for Erasable Programmable Read Only Memory. See PROM. 

Error Checking or Error Detection: Software routines that identify, and often 
correct, erroneous data. 

Execute: To perform the specified instructions in a command or program statement. 

Expression: A combination of constants, variables or array elements acted upon by — 

logical, mathematical or relational operators that return a numeric value. j ( 

File: A program or collection of data treated as a unit and stored on disk or 
tape. 

Firmware: Computer instructions stored in ROM, as in a game cartridge. 

Frequency: The number of sound waves per second of a tone. The frequency corre- 
sponds to the pitch of the audible tone. 

Full-Duplex Mode: In this mode, two computers can transmit and receive data at the 
same time. 

Function: A predefined operation that returns a single value. 

Function Keys: The four keys on the far right of the Commodore 128 keyboard. Each 
key can be programmed to execute a series of instructions. Since the keys can be 
SHIFTed, you can create eight different sets of instructions. 

GCR: The abbreviation for Group Code Recording, a method of storing information on 
a disk. The 1541 and 1571 disk drives can read, write and format GCR disks. 

Graphic Characters: Nonalphanumeric characters on the computer's keyboard. 

Graphics: Visual screen images representing computer data in memory (i.e., charac- 
ters, symbols and pictures). 

Grid: A two-dimensional matrix divided into rows and columns. Grids are used to 
design sprites and programmable characters. 
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Half-Duplex Mode: In this mode, data can be transmitted in only one direction at a 
time; if one device is sending, the other must simply receive data until it's time for 
it to transmit. 

Hardware: Physical components in a computer system, such as the keyboard, disk 
drives and printer. 

Hexadecimal: Refers to the base-16 number system. Machine language programs are 
often written in hexadecimal notation. 

Home: The upper-left comer of the screen. 

IC: The abbreviation for Integrated Circuit. A silicon chip containing an electrical 
ckcuit made up of components such as transistors, diodes, resistors and capaci- 
tors. Integrated circuits are smaller, faster and more efficient than the individual 
circuits used in older computers. 

Increment: To increase an index variable or counter with a specified value. 

Index: The variable counter within a programming loop. 

Input: Data fed into the computer to be processed. Input sources include the keyboard, 
disk drive, Datassette or modem. 

Integer: A whole number (i.e., a number containing no fractional part), such as 0, 1, 
2, etc. 

Interface: The point of meeting between a computer and an external entity, whether an 
operator, a peripheral device or a communications medium. An interface may be 
physical, involving a connector, or logical, involving software. 

I/O: The abbreviation for Input/Output. Refers to the process of entering data into the 
computer, or transferring data from the computer to a disk drive, printer or storage 
medium. 

Keyboard: Input component of a computer system. 

Kilobyte (K): 1024 bytes. 

Local Network: One of several short-distance data communications schemes typified 
by common use of a transmission medium by many devices at high-data speeds. 
Also called a Local Area Network, or LAN. 

Loop: A program segment executed repetitively a specified number of times. 

Machine Language: The lowest-level language the computer understands. The com- 
puter converts all high-level languages, such as BASIC, into machine language 
before executing any statements. Machine language is written in binary form, which 
a computer can execute directly. Also called machine code or object code. 

Matrix: A two-dimensional rectangle with row and column values. 

Memory: Storage locations inside the computer. ROM and RAM are two different 
types of memory. 

Memory Location: A specific storage address in the computer. There are 131,072 
memory locations (0-131,071) in the Commodore 128. 

MFM: The abbreviation for Modified Frequency Modulation, a method of storing 
information on disks. The 1571 disk drives can read and write to MFM disks. 

Microprocessor: A CPU that is contained on a single integrated circuit (IC). Micropro- 
cessors used in Commodore personal computers include the 6510, the 8502 and 
the Z80. 

Mode: A state of operation. 
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Modem: The acronym for MOdulator/DEModulator. A device that transforms digital ^ 

signals from the computer into analog electrical impulses for transmission over 
telephone lines, and does the reverse for reception. | ( 

Monitor: A display device resembling a television set but with a higher-resolution 
(sharper) image on the video screen. 

Motherboard: In a bus-oriented system, the board that contains the bus lines and edge 

connectors to accommodate the other boards in the system. j J 

Multi-Color Bit Map Mode: A graphic mode that allows you to display one of four 
colors for each pixel within an 8 by 8 character grid. See Pixel. 

Muiti-Coior Character Mode: A graphic mode that allows you to display four \ | 

different colors within an 8 by 8 character grid. ^ 

Multiple-Access Network: A flexible system by which every station can have access 

to the network at all times; provisions are made for times when two computers i 

decide to transmit at the same time. Lj 

Null String: An empty character (""). A character that is not yet assigned a character 

string code. Produces an illegal quantity error if used in a GET statement. -^ 

Octave: One full series of eight notes on the musical scale. i f 

Operating System: A built-in program that controls everything a computer does. 

Operator: A symbol that tells the computer to perform a mathematical, logical or 

relational operation on the specified variables, constants or array elements in the J 

expression. The mathematical operators are -I- , -, *, / and f . The relational Li 

operators are<, =,>,< =,> = and <>. The logical operators are AND, 
OR NOT and XOR. 

Order of Operations: Sequence in which computations are performed in a mathemat- 
ical expression. Also called Hierarchy of Operations. 

Parallel Port: A port used for transmission of data 1 byte at a time using 8 data lines, 
one for each bit. 

Parity Bit: A 1 or added to a group of bits that identifies the sum of the bits as odd or 
even, for error checking purposes. 

Peripheral: Any accessory device attached to the computer such as a disk drive, printer, | ' 

modem or joystick. [J 

Pitch: The highness or lowness of a tone that is determined by the frequency of the 

sound wave. See Frequency. ; -, 

Pixel: Computer term for picture element. Each dot that makes up an image on 
the screen is called a pixel. Each character on the screen is displaced within 
an 8 by 8 grid of pixels. The entire screen is composed of a 320 by 200 pixel _ 

grid. In bit-map mode, each pixel corresponds to a bit in the computer's ] j 

memory. U 

Pointer: A register used to indicate the address of a location in memory. 

Polling: A communications control method used by some computer/terminal systems Ti 

whereby a "master" station asks many devices attached to a common transmis- M 

sion medium, in turn, whether they have information to send. 

Port: A channel through which data is transferred to and from the CPU. 

Printer: Peripheral device that outputs the contents of the computer's memory onto a 
sheet of paper. This paper is referred to as a hard copy. 
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Program: A series of instructions that direct the computer to perform a specific task. 
Programs can be stored on diskette or cassette, reside in the computer's memory, 
I I or be listed on a printer. 

I ( Program Line: A statement or series of statements preceded by a line number in a 

program. The maximum length of a program line on the Commodore 128 is 160 
O characters. 

) I Programmable: Capable of being processed with computer instructions. 

PROM: The acronym for Programmable Read Only Memory. A semiconductor memory 
chip whose contents can be changed. 
j I Protocol; The rules under which computers exchange information, including the 

' ■ organization of the units of data to be transferred. 

Random Access Memory (RAM): The programmable area of the computer's memory 
n that can be read from and written to (changed). All RAM locations are equally 

/ ! accessible at any time in any order. The contents of RAM are erased when the 

computer is turned off. 

Random Number: A nine-digit decimal number from O.OOOWOOOl to 0.999999999 
generated by the RaNDom (RND) function. 

Read Only Memory (ROM): The permanent portion of the computer's memory. The 
contents of ROM locations can be read, but not changed. The ROM in the 
Commodore 128 contains the BASIC language interpreter, character-image pat- 
terns and the operating system. 

Register: Internal storage compartments with the microprocessor that communicate 
between system ROM, RAM, and themselves. 

Release: The rate at which the volume of a musical note decreases from the sustain 
level to 0. 

Remark: Comments used to document a program. Remarks are not executed by the 
computer, but are displayed in the program listing. 

Resolution: The fineness of detail of a displayed image, determined by the density of 
pixels on the screen. 

RGB! Monitor: A high-resolution display device necessary to produce the C128 80- 
column screen format. RGBI stands for Red/Green/Blue/Intensity. 

Ribbon Cable: A group of attached parallel wires, usually made up of 25 lines for 
RS-232 conmiunication. 

Ring Network: A system in which all stations are linked to form a continuous loop or 
circle. 

RS-232: A recommended standard for electronic and electromechanical specifications for 
serial communication. The Commodore 128 parallel user port can be treated as a 
serial port if accessed through software, sometimes with the addition of an 
interface device. 

Screen: A video display unit, which can be either a television or a video monitor. 

Screen Code: The number assigned to represent a character in screen memory. When 
you type a key on the keyboard, the screen code for that character is entered into 
screen memory automatically. You can also display a character by storing its 
screen code directly into screen memory with the POKE command. 

Screen Memory: The area of the Commodore 128's memory that contains the infor- 
mation displayed on the video screen. 
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Serial Port: A port used for serial transmission of data; bits are transmitted one bit 
after the other over a single wire. 

Serial Transmission: The sending of sequentially ordered data bits. \ 

Software: Computer programs (set of instructions) stored on disk, tape or cartridge that [^ 

can be loaded into random access memory. Software, in essence, tells the com- 
puter what to do. , 

Sound Interface Device (SID): The MOS 6581 sound synthesizer chip responsible 
for all the audio features of the Commodore 128. 

Source Code: A nonexecutable program written in a higher-level language than 

machine code. A compiler or an assembler must translate the source code into an | f 

object code (machine language) that the computer can understand. O 

Sprite: A programmable, movable, high-resolution graphic image. Also called a Mov- 
able Object Block (MOB). 

Standard Character Mode: The mode the Commodore 128 operates in when you 
turn it on and when you write programs. 

Start Bit: A bit or group of bits that identifies the beginning of a data word. - , 

Statement: A BASIC instruction contained in a program line. { j 

Stop Bit: A bit or group of bits that identifies the end of a data word and defines the '-' 

space between data words. 

String: An alphanumeric character or series of characters surrounded by quotation 1 / 

marks. jj 

Subroutine: An independent program segment separate from the main program that 

performs a specific task. Subroutines are called from the main program with the ^ 

GOSUB statement and must end with a RETURN statement. 

Subscript: A variable or constant that refers to a specific element in an array by its 
position within the array. 

Sustain: The midranged volume of a musical note. 

Synchronous Transmission: Data communications using a synchronizing, or clock- 
ing, signal between sending and receiving devices. 

Syntax: The grammatical rules of a progranuning language. \ i 

Tone: An audible sound of specific pitch and waveform. ) J 

Transparent: Describes a computer operation that does not require user intervention. 

Variable: A unit of storage representing a changing string or numeric value. Variable 

names can be any length, but only the fu^t two characters are stored by the ( 

Commodore 128. The first character must be a letter. ^ 

Video Interface Controller (VIC): The MOS chip (8564) responsible for the 40-column 
graphics features of the Commodore 128. 

Voice: A sound-producing component inside the SID chip. There are three voices 
within the SID chip so the Commodore 128 can produce three different sounds 
simultaneously. Each voice consists of a tone oscillator/waveform generator, an , , 

envelope generator and an amplitude modulator. ( 

Waveform: A graphic representation of the shape of a sound wave. The waveform 
determines some of the physical characteristics of the sound. 

Word: Number of bits treated as a single unit by the CPU. In an 8-bit machine, the 
word length is 8 bits; in a 16-bit machine, the word length is 16 bits. 
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Abbreviations, 670-673 
ABS, 73 
Accumulator, 127-129 

addressing, 138 

loading, 147-148 
ACPTR, 422-423 
ADC, 162 
Addition, 19 
Addressing 

absolute, 138-139, 143 

accumulator, 138 

immediate, 138 

implied, 139 

indexed, 141-143, 144-145 

indirect, 143-145 

modes, 137, 141-142 

relative, 140-141 

16-bit, 133-135 

table, 161-179 

zero-age, 139, 142 
ALT Mode, 497 
AND, 152, 162 
APPEND, 27 
Arithmetic 

instructions, 151-152 

operations, 18-20 
Arrays, 13, 16-18 
ASC, 73, 660-662 
ASL, 163 

Assembler, 126-127 
ATN, 73 
AUTO, 27 



BACKUP 27-28 
BANK, 28 
BASIC 

advanced programming techniques, 

103-107 
color RAM in C128, 218 
color RAM in C64, 218-219 
C128 bit map mode, 221 
crunching of programs, 95 
C64 bit map mode, 222 
C64 character modes, 222 
entering machine language subrou- 
tines through, 198-202 
error messages, 644-647 
intelligent use of, 97 
mixed with machine language, 

198-205 
placement of machine language 

routines with, 203-205 
relocating, 106 

screen memory in C128, 215-217 
screen memory in C64, 217 
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BASIN, 423-433 
BCC, 163 
BCS, 163 

BEGIN/BEND, 28-29 
BEQ, 164 

BIOS (Basic Input Output System), 
486-489, 500, 677-683, 704- 
705 
BIT, 153-154, 164 
Bit map mode 112, 221, 222 

data, 241-243 

80-column (8563) chip, 314-320 

multi-color, 243-245 

standard, 239-243 

standard sprites, 283-284 

video matrix, 240-241, 244 
Bits 

masking, 97-98 

16-bit addressing, 133-135 

values in a byte, 98-99 
BLOAD, 29 
BMI, 164 
BNE, 164 

BOOT, 29-30, 446-447 
BOX, 30, 113-114 
BPL, 165 
BRK, 165 
BSAVE, 31 
BSOUT, 433 
Buffer 

control block, 685 

routine, 93 
BUMP, 73-74 
Bus 

architecture, 560-562 

color data, 562 

display, 562 

expansion, 635-637 

loading, 567-568 

multiplexed address, 561 

processor, 560 

serial, 633-634 

shared address, 561-562 

translated address, 560-561 
BVC, 165 
BVS, 165 



Cassette connector, 398 
CATALOG, 31 
CHAR, 31-32, 115 
Character mode 

accessing character ROM, 229 

character memory, 226-229, 
234-235 

color data, 225-226, 235-237 

color memory, 226 



C128 BASIC, 219-220 

C64 BASIC, 222 

multi-color, 233-237 

programmable characters, 230-233 

screen location, 224, 234 

screen memory data, 224-225 

standard, 223-233 
CHKIN, 429-430 
CHR$, 74, 660-662 
CIA (6526) chip, 611-623 

control registers 622-623 

description, 611, 618-622 

electrical characteristics, 613-615 

interface signals, 615-616 

interrupt control, 621-622 

serial port, 620-621 

timing, 616-617, 618-620 
CINT, 410, 414 
CIOUT, 423 

CIRCLE, 32-33, 1I5-U6 
CKOUT 430-431 
CLALL, 439 
CLC, 166 
CLD, 166 
CLI, 166 

CLOSE, 33, 428-429 
CLOSE ALL, 443 
CLR, 33 

CLRCH, 431-432 
CLV, 166 
CMD, 33 
CMP, 167 
CMPSTA, 456 
COLLECT, 34 
COLLISION, 34, 267 
COLOR, 34-35, 116-117 
Color mode 

extended background, 237-239 

memory map, 664 

sprites, 283-285 

See also Memory, color RAM 
Commands, 12 

basic, 27-72 

CP/M, 481-482, 483 

format, 25-27 

graphics, 113-122 

machine language monitor, 186-194 

sprites, 267-270 

summary, 674-675 

See also specific commands 
Commodore 128. See C128 Mode 
Commodore 64. See C64 Mode 
Complex Interface Adapter. See CIA 

(6526) chip 
CONCAT, 35-36 
C128 Mode, 2-3, 5 

BASIC bit map mode, 221 
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CI 28 Mode (continued) 


DBY, 168 


FETCH, 43 


character memory, 219-220 


DIM, 38 


Files 


character set availability, 222 


DIRECTORY, 38-39 


CP/M, 479-481 


color RAM in BASIC, 218 


Directory, 375 


creating and storing, 376-378 


CP/M disk format, 493-494 


Disk drive 


disk drive, 374-376 


memory map, 502-540 


copies, 482, 485 


merging, 106-107 


ROM cartridge, 471-472 


device number, 378 


FILTER, 43, 337-338, 348-351 


screen memory in BASIC, 215-217 


directory, 375 


FNxx, 74 


switching from mode to mode, 6 


formatting, 372-373 


FOR/TO/STEP/NEXT, 44 


using C64 fimction key values, 95 


replacing files or programs, 374 


FRE, 75 


Configuration Register. See Memory 


retrieving files or programs, 375-376 


Function keys 


Connectors, 652-657 


saving progiams, 373-374 


changing, 95 


Constants, 12-15 


verifying files or programs, 


programming, 94 


floating-point, 13 


374-375 


using C64 values, 95 


integer, 13 


Disk Parameter Block, 685 


Functions, 72-86 


string, 14-15 


Division, 19-20 


errors, 101 


CONT, 36 


DLCHR, 450 


user, 685-704 


Control codes, 666-668 


DLOAD, 39 


See also specific functions 


COPY, 36 


DMA CALL, 444-445 




COS, 74 


DO/LOOPAVHILE/UNTIL/EXrr,39-40 


G 


CP/M, 676 


DOPEN, 40 


GET, 44-45 


BIOS routines, 677-683, 704-705 


DOS errors, 101,648-651 


GET#, 45 


calling user function, 702-704 


Dot matrix printer, 378-379 


GETCFG, 452 


commands, 481-482, 483 


DRAW, 41, 117-118 


GETIN, 438-439 


control characters for line editing. 


Drive Table, 684-685 


GETKEY, 45 


482, 484 


DSAVE, 41 


G064,45 


copies of disks and files, 482, 485 


DVERIFY, 42 


GOSUB, 45-46 


disk organization, 491-495 




GOTO/GO TO, 46 


enhancements, 479 


E 


GRAPHIC, 46, 119 


files, 479^81,482, 485 


Editor. See Screen editor 


Graphics 


keyboard scanning, 496-497 


80-column (8563) chip, 292-334 


commands, 113-122 


memory map, 709-720 


bit map mode, 314-320 


power behind, 208-263 


mode, 4 


Block Write and Block Copy, 


programming, 110-122 


requirements for system, 478 


312-313, 333 


system, 215-223 


switching from mode to mode, 7 


characters, 296-297, 301-304, 325, 


GSHAPE,46, 119-120 


system layout, 486-487 


328, 333 




system memory organization. 


cursor, 313-314, 326 


H 


489-491 


display, 299-301, 326, 327-334 


Hardware 


system operations, 500 


ftames, 297-299 


components, 4-5 


system release, 8 


RAM, 304-305, 309^313, 327-334 


specifications, 556-641 


CPX, 167 


registers, 304-309, 324-334 


system architecture, 557-558 


CPY, 167 


scrolling of screen, 320-323, 


See also specific components 


C64 Mode, 3, 5, 444 


328-331 


HEADER, 47 


BASIC bit map mode, 222 


8502 microprocessor, 569-574 


HELP, 47 


BASIC character modes, 222 


description, 569 


HEX$, 75 


color RAM in BASIC, 218-219 


electrical specification, 569-571 


Hexadecimal notation, 136-137 


CP/M disk format, 492-493 


processor timing, 571-574 




input/output assignments, 546-554 


END, 42 


1 


memoiy map, 540-554 


ENVELOPE, 42, 336-337, 347-348 


IF/THEN/ELSE, 47-48 


ROM cartridge, 472 


Environmental specifications, 568 


INC, 169 


screen memory in BASIC, 217 


EOR, 152, 168 


INDFET, 454-455 


switching from mode to mode, 7 


Errors 


INDSTA, 455 


using function key values, 95 


BASIC messages, 644-647 


INPUT, 48 


Cursor, 313-314, 326 


DOS, 101, 648-651 


INPUT*. 49 




functions, 101 


Input/output, 5, 372-400, 727 


D 


logic, 99 


BIOS (Basic Input Output System), 


Daisy wheel printer, 378 


syntax, 99 


486-489, 500, 667-683, 704- 


DATA, 36 


tracing of, 101 


705 


Datassette, 389-390 


trapping of, 100 


controller ports input, 390-393 


Data structures, 684-685 


See also Programming, debugging 


C64 assignments, 546-554 


DCLEAR, 37 


Escape codes, 669 


Datassette output, 389-390 


DCLOSE, 37 


Exponentiation, 20 


disk drive, 372-376 


Debugging. See Programming 


Expressions, 18 


files, 376-378 


DEC, 168 


arithmetic, 18 


modem output, 381 


DEF FN, 37 


string, 24 


output control, 393-394 


DFIKIE, 38 




pinouts, 394-400 


Device numbers, 457 


F 


printer output, 378-381 


DEX, 168 


FAST, 43 


RS-232 channel, 382-388 
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Input/output (continued) 


routine, 93-94 




screen outpuut, 388-389 


LOCATE, 51, 120 




INSTR, 75 


LOG, 77 


o 


Instructions 


Logic 


i 

1 


arithmetic, 151-152 


eiTors, 99 


\ 


branching, 154-156 


instructions, 151, 152-153 




compare, 15ft-151 


Logical operators, 21-22 




counter, 148-149 


LSR, 171 


*^ 


entering machine language in 




1 


monitor, 183-184 


M 


I 


jump, 159-160 


Machine language, 124-179 




logical, 151, 152-153 


character memory, 223 




machine language, 145-179, 


color RAM, 219 


o 


183-184 


definition, 124 


' ! 


multiple, 96 


entering programs, 182-195 


' 1 


register to memory, 147-148 


entering subroutines through 




register transfer, 156 


BASIC, 198-202 




return, 160 


executing programs, 184-186 


- 


lotate, 156, 157 


instructions, 145-179, 183-184 




set and clear, 158-159 


mixed with BASIC, 198-205 


1 


shift, 156-157 


monitor, 127 




stack, 160 


monitor commands, 186-194 




table, 161-179 


operand field, 126 


n 


See also specific instructions 


operation code field, 125 


' 1 


INT, 75-76 


placement of programs in memory. 


/ ! 


Interrupt service routine, 258-263 


202-203 




INX, 169 


placement of routines with BASIC, 




INY, 169 


203-205 


n 


lOBASE, 442 


programming of SID chip, 352-358 


i 


lOINTT, 409-410, 415-416 


screen memory, 217-218 


t ; 


IRQ pin, 411^14 


Z80, 702-708 
MEMBOT, 420-421 




J 


Memory, 4 


■n 


IMP, 169 


banked, 208-213, 218, 490 


JMPFAR, 453-454 


character (ROM), 219-222, 226-229 


'' 1 


JOY, 76 


color RAM, 218-219, 225-226, 




Joysticks, 390-392 


236, 238, 243, 245 




JSR, 170 


Configuration Register, 460-463 


i 
1 


JSRFAR, 453-454 


CP/M system memory organization. 




489-491 


K 


crunching, 95 




Kemal caUs, 414-457 


dynamic RAM, 624-626 




Kenial/Editor Hags, 539-540 


80-column (8563) chip, 299-301, 


(— 1 


Kemal jump table, 537-539 


304-305, 309-313, 327-334 


1 


Kemal routines, 403-406 


management, 5, 458-471, 583-587 


j 1 


KEY, 49, 421^22 


maps, 502-554, 663-664, 709-720 




Keyboard, 640-642, 727 


Mode Configuration Register, 




connector pinout, 640-641 


465-466 


(^ 


scanning, 496-497, 588-589 


placement of machine langiuge 


1 


Keywords. See Reserved system 


programs, 202-203 


) 


words 


preconfiguration, 462-465 
RAM Configuration Register, 




L 


467-469 


r^ 


LDA, 147-148, 170 


RAM and 80-colunm (8563) chip. 


) > 


LDX, 170 


304-305, 309-313 327-334 


/ 1 


LDY, 171 


RAM organization, 566-567 




LEfn, 76 


RAM and system architecture. 




LEN, 77 


557-558, 729 




LET, 49-50 


ROM, 627-632 


■7 


Light pen, 393, 593 


ROM banking, 627 


1 
■ 1 


UST, 50 


ROM cartridge startup, 471-472 


I 


LISTN, 425 


ROM chip, 630, 632 




LKULPA, 448^*49 


ROM organization, 564 




LKUPSA, 448-449 


ROM pinout, 629, 631 


^ 


LOAD, 50, 434-435 


ROM and system architecture. 


i 


Loading 


557-558, 729 




accumulator, 147-148 


ROM timing, 628 


- 


bus, 567-568 


RS-232 channel, 387-388 



screen (RAM), 215-218 

16K video banks, 210-212 

64K RAM banks, 208-210 

split-screen mode, 246-247 

storage, 12-13, 148 

switching banks, 459-460 

system organization, 562-567 

See also Character mode 
Memory Management Unit (MMU). 

See Memory, management 
MEMTOP, 419-420 
Menu, 92 
MFM. See Modified Frequency 

Modulation 
MID$, 77 
Modem, 381 
Modified Frequency Modulation 

(MFM), 705-708 
Module communication, 486-487 
MONITOR, 51 
Monitor, 388-389 

entering machine language pro- 
grams in, 183-184 

field descriptors, 187-188 

machine language commands, 
186-194 

manipulating text within, 194-195 
Mouse, 392 

Movable object blocks. See Sprites 
MOVSPR, 51-52, 267-268 
Multiplication, 19 
Music, 336-369 

coding a song from sheet music, 
341-344 

equal-tempered scale values, 366, 
607-608 

uistruments, 336-337 

notes, 338-340, 341-343, 366-369 

statements, 336-341 

N 

NEW, 52 

Non-Maskable Interrupt (NMI) vector, 

407-408 
NOP, 160, 171 

O 

ON, 53 

OPEN, 53-54, 427-428 

Operating system, 402-475 

CP/M components, 486 

Kemal calls, 414-457 

Kemal routmes for programs, 
403-406 

vectors, 407-414 
Operations 

arithmetic, 18-20 

hierarchy of, 22-23 

string, 24 
ORA, 152, 172 
Output. See Input/output 

P 

Paddles, 392 

Page pointers, 470-471 

PAINT, 54-55, 120-121 

PEEK, 77 

PEN, 78 
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Performance specifications, 567-568 

PFKEY, 450-451 

PHA, 172 

PHOENIX, 448 

PHP, 172 

Pinouts, 394-400 

PLA, 172 

See also Progiammed Logic Array 
PLAY, 55-56, 338-339 
PLOT, 441 
PLP, 173 
POINTER, 78 
POKE, 56 
Ports, 372, 727 

controller, 390-393, 398-399 

expansion, 399-400 

for peripheral equipment, 652-657 

serial, 394 

user (RS-232 channel), 394-396 

See also specific controller devices 
POS, 79 
POT, 79 

PRIMM, 456-457 
PRINT, 56, 100 
PRINT#, 57, 380 
Printer, 378-380 

control, 380-381 

daisy wheel, 378 

dot matrix, 378-379 
PRINT USING, 57-58 
Processors, 4, 560 
Program counter, 132 
Programmed Logic Array, 581-582, 

723 
Programming 

advanced BASIC techniques, 
103-107 

debugging, 99-101 

of 80-column (8563) chip, 292-334 

escape, 106 

of function keys, 94 

graphics, 110-122 

of SID chip in machine language, 
352-358 



definition, 376 
Kemal routines, 403-406 
printing program listing, 379 
printing through a program, 380 
replacing, 374 

retrieving from disks, 375-376 
saving, 373-374 
verifying, 374-375 
PUDEF, 58-59 



RAM. See Memory 

RAMTAS, 416 

Raster interrupt split screen program, 

248-258 
RCLR, 79-80 
ROOT, 80 
RDTIM, 437 
READ, 59 
READSS, 426 
RECORD, 59-60 
Registers, 126 
CIA (6526) chip, 622-623 



80-column (8563) chip, 304-309, 
324-334 

8502 microprocessor, 127 

8563 video controller, 595 

interrupt, 591-592 

taster, 591 

shadow, 213-214, 539-540 

SID chip, 359-365, 528-530 

status, 130-132 

System Version, 471 

VIC chip, 524-527, 591-592 

X and Y index, 129-130, 141-143 
Relational operators, 20-21 
REM, 60, 96 
RENAME, 60 
RENUMBER, 60-61 
Reserved system symbols, 88-89 
Reserved system words, 86-88 
RESET, 408 
RESTOR, 416-417 
RESTORE, 61,407-408 
RESUME, 61-62 
RETURN, 62 

RGBI video connector, 397-398 
RGR, 80-81 
RIGHTS, 81 
RND, 81 
ROL, 173 
ROM. See Memory 
ROR, 173 
RSPCOLOR, 82 
RSPPOS, 82 
RSPRTTE, 83 
RS-232 channel, 382-388, 394-396 

closing, 385-387 

data, 385 

memory locations, 387-388 

opening, 382-385 

sample program, 387 
RTI, 174 
RTS, 174 
RUN, 62 
RWINDOW, 83 



SAVE, 63, 435-436 
SBC, 174 

SCALE, 63, 121-122 
Schematics, 721-729 
SCNCLR, 64 
SCRATCH, 64 
Screen editor 

control codes, 474 

escape codes, 473 

intermediate storage, 213-214 

interrupt-driven, 214-215, 247-248 

jump table, 474-475 
Screen output, 388-389 

See also Graphics; Video 
Scrolling 

of 8563 screen, 320-323, 328-331 

of 8564 VIC chip, 593 
SCRORG, 440 
SEC, 175 
SECND, 418-419 
SED, 175 
SEI, 175 
SETBNK, 451 



SETLFS, 426-427 
SETMSG, 418 
SETNAM, 427 
SETTIM, 436-437 
SETTMO, 422 
SGN, 84 

SID (Sound Interface Device) chip, 
336, 723 

audio input, 351-352 

electrical characteristics, 605-606 

envelope generators, 608-610 

filter, 337-338, 348-351, 363 

pins, 600, 602-604 

programming in machine language, 
352-358 

registers, 359-365, 528-530 

specifications, 599-604 

synchronization and ring modula- 
tion, 358-359 

and system architecture, 558 

timing, 606-607 
SIN, 84 
SLEEP, 64, 99 
SLOW, 64 

SOUND, 65, 339-340 
Sound, 5, 336-369 

characteristics, 345-348 

statements, 336-341 

volume, 347 
Sound Interface Device. See SID chip 
Space elimination, 95 
SPC, 84 
SPINP, 442-443 
Split-screen mode, 245-248 

organization in memory, 246-247 

raster interrupt program, 248-258 
SPOUT 442—443 
SPRCOLOR, 65-66, 268-269 
SPRDEF, 66, 269-270, 276, 279 
SPRITE, 66-67, 272-273 
Sprites, 266-290 

adjoining, 274-276 

collision priorities, 289-290 

color, 283-285 

commands, 267-270 

creation of image, 279-281 

creation procedure in definition 
mode, 270-274 

display priorities, 288-289 

enablement, 282 

expansion of size, 287-288 

inner workings, 279-290 

pointers, 281-282 

positioning on screen, 285-287 

program examples, 276-278 
SPRSAV, 67, 273 
SQR, 84 
SSHAPE/OSHAPE, 68-69, 122, 

273-274 
STA, 175 

Stack pointer, 132-133 
STASH, 69 
Statements, 12 

basic, 27-72 

format, 25-27 

See also specific statements 
STOP, 69, 100, 437-438 
Storage. See Files; Memory, storage 
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STORE, 148 


Text 




composite connector, 396-397 


STR$,84-85 


display, 111-112 




display codes, 658-659 


String, 497 


manipulation within machine 


8563 controller, 595-598 


STX, 176 


monitor, 194-195 




features, 110-112 


STY, 176 


TKSA, 419 




40/80 column display, 498-499 


Subtraction, 19 


TouchTone frequencies. 


103-104 


interface chip, 524-527, 557-558, 


SWAP, 69 


TRAP, 70 




588-594, 638-639 


SWAPPER, 449 


Trigonometric functions. 


665 


RGB! connector, 397-398 


Symbols. See Reserved system 


TROFF, 70 




16K banks, 210-212 


symbols 


TRON, 71 




types of screen display, 111-112 


Syntax, 96, 99 


TSX, 177 




VOL, 71, 341 


Synthesizers, 336 


TXA, 177 






SYS, 69^70 


TXS, 177 




W 


System Control Block, 684 


TYA, 177 




WATT, 71-72 


System schematics, 721-729 






WIDTH, 72, 122 


System Version Register, 471 


U 




Wildcard characters, 480 




UDTIM, 439-440 




WINDOW, 72, 102 


T 


UNLSN, 424 




Windowing, 102 


TAB, 85 


UNTLK,424 






TALK, 425 


User functions, 685-704 




X 


TAN, 85 


User number, 480 




XOR, 86 


TAX, 176 


USR, 85-86 






TAY, 176 






Z 


Telephones 


V 




Z80 microprocessor, 574-580, 685 


detecting carrier, 105 


VAL, 86 




bus interface, 575 


programming to be on or off hook. 


Variables, 12-13, 15-16 


,96 


control interface, 575 


104-105 


VECTOR, 417 




electrical specifications, 579-580 


ringing, 104 


VERIFV^, 71 




machine language, 702-708 


rotary (pulse) dialing, 105-106 


VIC chip. See Video, interface 


processor switching, 576-577 


TouchTone frequencies, 103-104 


chip 




signal description, 577-578 


TEMPO, 70, 340-341 


Video, 4, 725 




system description, 575-577 
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Advanced Machine Language on the C64 
by Lothar Englisch (Abacus) 

The Anatomy of the Commodore 64 I 

by Michael Angerhausen, Dr. Achim Becker, Lothar Englisch, and Klaus Gerits 
(Abacus) 

Artificial Intelligence— How Computers Think ! 

by F. David Peat (Simon and Schuster) 

Basic 64 BASIC \ 

by James Coan (Hayden Publications) {_ 

C64 Assembly Language Arcade Game Programming 
by Steve Bress (TAB) T 

C64 Graphics and Sound Programming '- 

by Stan Krute (TAB) 

The Commodore 64 Programmer's Reference Guide 
by Commodore Business Machines (Howard W. Sams) '*■ 

The Complete Commodore Inner Space Anthology 
by Karl J.H. Hildon (Transactor Publishing) 

Computer Primer 
by Ann Cavanaugh (Trillium Press) , - . 

CP/M Bible [J 

by Mitchell Waite and John Angermeyer (Howard W. Sams) 

The Digital Research CP/M Plus Programmer's Guide \ i 

by Digital Research (_^ 

The Digital Research CP/M Plus System Guide 
by Digital Research [ 

The Digital Research CP/M Plus User's Guide ^- 

by Digital Research _ 

Inside Commodore DOS | 

by Richard Emmers (Reston Publishing) *- 

Introducing 64 Machine Code - 

by Ian Sinclair (Prentice Hall) } 

Microcomputer Graphics 
by Roy E. Meyers (Addison- Wesley) 

Programming the 6502 
by Rodney Zaks (Sybex) 

Z80 and 8080 Assembly Language Programming 
by Kathe Spracklen (Hayden) 
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Commodore 128 
Programmer's Reference Guide 

This boo* -s an indispensable fe-fereniC* gunj^and sou^cBtiDak toranyana using 
th« new snti po we-rf ui Commodore iza compuler This maciiine ha^ man v ne^^ 
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